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 defaultpageSize
. 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.
API Reference