Welcome to the Charity Navigator Data API

Welcome, and thanks for your interest in Charity Navigator's Data API.

Note: The Data API replaces the first-generation Charity Navigator API, adding more complete data coverage, improved documentation, RAPID-ML and OpenAPI specifications with a Swagger-UI test sandbox. If you're looking for documentation on the first-generation API, it's available here.

Quick Start

New Users

If you haven't already registered on the Charity Navigator API portal, click here to get started.

Current Users

If you have already registered an application with the first-generation API:

Click here to open the applications management page.
Click "Create a new application", then click "Data API"
Fill in the form to register your new application.

Please Note: The API management system registers each application with a single API. You'll need to use your newly assigned app_id and app_key with the new Data API. You can still use your previous app credentials for the first-generation Charity Navigator API.

About the API

The Charity Navigator Data API provides access to Charity Navigator's research and reference data, covering charitable organizations, ratings, lists, and other related content.

The data model and API are described in RAPID-ML, and translated to industry-standard OpenAPI format (currently version 2.0) for interactive documentation and overall interoperability.

Charity Navigator is working in partnership with RepreZen, and building the API solution using RepreZen API Studio.

How to Contact the Charity Navigator API Team

Please send questions, comments and bug reports to:

apisupport@charitynavigator.org

API Documentation

API documentation is available in three forms:

Static API Reference

The Static API Reference provides complete data model details in a format that's easy to read and navigate.

Interactive API Diagram

The Interactive API Diagram gives you a visual overview of the API's resources and methods.

Interactive Swagger-UI Documentation

The Interactive Swagger-UI Documentation on this page lets you explore and exercise the live data API.

Visual Indicators

Many of the data properties listed in the documentation have one or more icons, indicating something about the inclusion criteria or usage of the property.

Icon	Meaning
	Only available for rated charities.
	Included with the paid Content Subscription.

API Changelog

See the changelog for a history of changes to the Data API.

API Specifications

You can also download machine-readable API specifications in RAPID-ML and Swagger-OpenAPI 2.0 formats:

Swagger/OpenAPI 2.0 Definition

RAPID-ML Model

Working with the API

Base URL

The base URL for the Data API is:

https://api.data.charitynavigator.org/v2

Authentication

All requests sent to the Data API require two query parameters for authentication:

app_id is the identity of the application, which you can share freely as needed.
app_key is a password for the application that you should protect carefully.

Both of these are assigned by the 3Scale API Management platform. You can use the API Keys link in the navigation bar above to inspect your registered applications and their credentials.

The Swagger UI on this page makes it easy to insert your application credentials: Clicking in the app_id and app_key fields displays a popup window with your registered apps. Just click the app name to populated the field. You'll need to do this twice, once for the app_id and again for the app_key:

NOTE: The application credential pop-up will only be available if:

You have an active account on the Charity Navigator developer portal;
You are logged into your account; and
You have registered an application with the Charity Navigator Data API.

Hyperlinks

The Charity Navigator data API uses a combination of embedded objects and hyperlinks to provide access to related data structures. Hyperlinks are native to RAPID-ML, and translated to _rapid_links in the OpenAPI schema.

For example, here's a response showing a summary representation of an organization:

{
  "ein": "411867244",
  "orgID": 9037,
  "charityName": "Home for Life",
  "currentRating": {
    "score": 64.34,
    "rating": 1,
    "ratingImage": "http://charitynavigator.org/images/r1.png",
    "financialRating": {
      "score": 65.75,
      "rating": 1
    },
    "accountabilityRating": {
      "score": 63,
      "rating": 1
    }
  },
  "category": {
    "categoryName": "Animals"
  },
  "organization": {
    "_rapid_links": {
      "canonical": {
        "href": "http://api.CharityNavigator.com/v1/organizations/411867244"
      }
    }
  }
}

In the example above, the currentRating is represented as an embedded structure. The organization is represented as a canonical hyperlink to an organizationObject resource at the specified URL.

Note: Hyperlinks returned by the API must have the app_id and app_key credentials appended to the query string before they can be used to retrieve data from the Data API. To maintain security, the service does not return URLs with credentials pre-specified, so you will need to add these to the query string before invoking a GET request on the URL.

Paging

Methods that can return large data sets include two optional parameters to control paging:

pageSize specifies the maximum number of objects to return in a single response message. The default value is 100. If specified, it must be an integer value between 1 and 1,000.
pageNum specifies the page number to return, in case the number of available objects in the result set is greater then the specified or default pageSize. The default value is 1. Any value greater than the number of pages in the result set will return a 404 error.

Paged responses will include a CN_Result_Count header, indicating the total number of available objects in the result set. This may be used by the client in combination with pageSize to compute the number of pages of available data.

Note: This header was formerly named objectCount. That header is still produced as well, but should be considered deprecated.

Note: The Data API provides a maximum of 10,000 objects. The API will return a 400 error response if the requested starting position, computed as ((pageNum-1) * pageSize) + 1, is greater than the maximum supported result size of 10,000 objects. The Data API is not designed for bulk data transfer of very large data sets. Contact the Charity Navigator API Team to inquire about the availability of bulk data subscription plans.

Presentation and Attribution

If your application will be showing data from the Charity Navigator API, you will generally be required to attribute the data to Charity Navigator, in accordance with the User Agreement.

The API includes image URLs and other properties, which should help in creating a user-friendly presentation. If you have specific requirements, suggestions, or questions about attribution and linking requirements, please let us know.

Scheduled Maintenance

The API Team will announce scheduled maintenance downtime in advance, usually with at least three days notice. Wherever practical, the team will perform scheduled maintenance between 7:00 and 8:00 am, US Eastern time.

If you have routine processing tasks that use Charity Navigator APIs, we recommend that you avoid running them during this regular maintenance window.