Charity Navigator API Documentation (1st Generation)
About the API
This documentation describes the first-generation API, which provides access to Charity Navigator's ratings, and basic information from the database of IRS registered nonprofits.
Note: The new Charity Navigator Data API is available!
The new Data API adds more complete data coverage, RAPID-ML and OpenAPI specifications, and a Swagger-UI test sandbox.
Inspecting the API Schema
The new Data API adds more complete data coverage, RAPID-ML and OpenAPI specifications, and a Swagger-UI test sandbox.
http://api.charitynavigator.org/api/v1/?format=xml
This lists all available API resources. Every resource has list_endpoint and schema. We can retrieve resource schema, for example “categories”:
http://api.charitynavigator.org/api/v1/categories/schema/?format=xml
This lists out the default_format this resource responds with, the fields on the resource & the filtering options available. This information can be used to prepare the other aspects of the code for the data it can obtain & ways to filter the resources.
The format=json or format=xml is an override required to make things look decent in the browser (accept headers vary between browsers). API properly handles the Accept header so the following will work properly:
``curl -H “Accept: application/json” http://api.charitynavigator.org/api/v1/categories/schema/
But if you’re sure you want something else (or want to test in a browser), API lets you specify ?format=... when you really want to force a certain type.
Pagination
By default, you get a paginated set of objects (20 per page is the default). In the meta, you get a previous & next. If available, these are URIs to the previous & next pages.
For example:
<meta type="hash">
<next>http://api.charitynavigator.org/api/v1/causes/?offset=20&limit=20&format=xml</next>
<total_count type="integer">34</total_count>
<previous type="null"/>
<limit type="integer">20</limit>
<offset type="integer">0</offset>
</meta>
Max limit size is 100.
API methods
After registration you will receive your own unique APP_ID and APP_KEY. These keys are required for every API call.
- Organization Search
- Organization Detail*
- Organization History*
- Categories
- Causes
- Celebrities
- Celebrity Types
- Celebrity Organizations
- Celebrity Relationships
- Countries
- Country Organizations
- Country Regions
- Lists
- List Organizations
*Requires Premium Subscription
Organization Search
This method enables you to search the entire database of IRS registered nonprofits. By default, results are restricted to rated organizations. Use the "rated" parameter to expand your search to all organizations. The search parameters and response values that apply to unrated organizations are limited.
Create a Search request [GET]:
Search parameters (at least one parameter must be passed):
Parameter Date Type Required/Optional Description rated number optional 1=Rated (default), 0=Unrated, 2=All Parameters below apply to both rated and unrated organizations. term string optional organization name or keyword, ex. "leukemia" or "Red Cross" ein string optional Employer Identification Number: unique number assigned by the Internal Revenue Service state string optional Two letter state abbreviation Parameters below apply to rated organizations only. letter string optional First letter of the organization's name (excludes "The") scope number optional The geographic scope of the charity's work (1=Regional, 2=National, 3=International) category number optional CategoryID (see the Categories method) cause number optional CauseID (see the Causes method) rating string optional Star Rating (0,1,2,3,4) OR "Donor Advisory" orgid number optional Charity Navigator's unique identifier size number optional (integer: 1=Less than 3.5 mill, 2= Between 3.5 and 13.5 and 3= Greater than 13.5) Response Values:
Name Type Definition Values are returned for the following fields for both rated and unrated organizations. ein string Employer Identification Number: unique number assigned by the Internal Revenue Service Charity_Name string Common Name of the organization URL string link to organization's profile page at Charity Navigator city string City for this organization state string State for this organization Subsection string Subsection of the IRS Code granting nonprofit status to this organization Deductibility string Statement of whether or not contributions to this organization are tax-deductible FoundationStatus string This organization's status as a public charity or private foundation. Applies to organizations in Subsection 501(c)(3). Rank number weight of search term Values are returned for the following fields for rated organizations only. Unrated organizations will return empty fields. OrgID number Charity Navigator's unique identifier Category string One of the 9 categories Cause string One of the 34 sub-categories Tag_Line string Slogan or brief summation of the charity's mission. Ex: "Helping people prevent, prepare for and respond to emergencies" OverallRtg string Returns the rating of 0, 1, 2, 3, 4 or Donor Advisory OverallScore number Overall score on a scale from 0 to 70 points Example search GET:
Example answer:
- [
- {
- “Category”: “Animals”, “city”: “LA”, “OverallRtg”: “2”, “Charity_Name”: “Alley Cat Allies”, “OverallScore”: “46.37”, “state”: “CA”, “OrgId”: 9999, “Rank”: 111, “Cause”: “Animal Rights, Welfare, and Services”, “Tag_Line”: “The cats’ leading advocate”, “Subsection”: “501(c)(3)”, “Deductibility”: “Contributions are deductible”, “FoundationStatus”: “Organization which receives a substantial part of its support from a governmental unit or the general public 170(b)(1)(A)(vi)”, “ein”: “22222222”
}, {
“Category”: “Animals”, “city”: “Lakewood”, “OverallRtg”: “1”, “Charity_Name”: “Cat Care Society”, “OverallScore”: “34.84”, “state”: “CO”, “OrgId”: 8888, “Rank”: 999, “Cause”: “Animal Rights, Welfare, and Services”, “Tag_Line”: “The best little cat house in the west”, “Subsection”: “501(c)(3)”, “Deductibility”: “Contributions are deductible”, “FoundationStatus”: “Organization which receives a substantial part of its support from a governmental unit or the general public 170(b)(1)(A)(vi)”, “ein”: “44444444”}
]
Organization Detail (Premium Subscription Required)
Fields returned:
- orgid
- ein
- charity_name
- categoryid
- causeid
- category
- cause
- tag_line
- fundraising_efficiency
- fundraising_expenses_ratio
- program_expenses_ratio
- administration_expenses_ratio
- primary_revenue_growth
- program_expenses_growth
- working_capital_ratio
- mission
- street_address_1
- street_address_2
- city
- state
- zip
- cob_name
- cob_title
- current_ceo_name
- current_ceo_title
- financial_score
- financial_rating
- accountability_score
- accountability_rating
- overall_score
- overall_rating
- fundraising_expenses
- administration_expenses
- program_expenses
- total_expenses
- total_revenue
- total_net_assets
- boardlist_status
- stafflist_status
- auditedfinancial_status
- form990_status
- privacy_status
- loanstoorfromofficers
- loanstoofficers
- materialdiversionofassets
- boardmeetingminutes
- distributes990toboard
- conflictofinterestpolicy
- whistleblowerpolicy
- recordsretentionpolicy
- reportsceoandsalary
- ceocompensationprocedure
- compensatesboard
- independentaudit
- boardcomposition
- phone_number
- general_email
- subsection
- deductibility
- foundation status
Get organizations by id - for example 4500:
Get organizations by ein - for example 411867244:
Categories
Fields returned:
- categoryid
- category
- description
List of all categories:
Get category by id - for example 4:
Causes (sub-categories)
Fields returned:
- causeid
- cause
- category
- categoryid
- description
List of all causes:
Get causes by id - for example 4:
It has Category Resource url in results.
Celebrities
Fields returned:
- celebrityid
- fname
- mname
- lname
- typeid
- type
- charity_count
List of all celebrities:
Get celebrities by id - for example 4:
Celebrity Types
Fields returned:
- typeid
- type
List of all celebrities types:
Get celebrities types by id - for example 4:
Celebrity Organizations
Fields returned:
- fname
- mname
- lname
- celebrityid
- orgid
- typeid
- relationshipid
- charity_name
- relationship
- type
List of all connections between organizations and celebrities:
It has Celebrity Resource in results.
It has Organization Resource url in results.
It has Celebrity Relation Resource in results.
Celebrity Relationships
Fields returned:
- relationshipid
- relationship
List of all celebrity relationships:
Get celebrity relationships by id - for example 1:
Countries
Fields returned:
- countryid
- country
- regionid
- charity_count
List of all countries:
Get countries by id - for example 4:
It has Region Resource in results.
Country Organizations
Fields returned:
- countryid
- orgid
- regionid
- country
- region
- charity_name
List of all organization in countries:
It has Country Resource in results.
It has Organization Resource in results.
Country Regions
Fields returned:
- regionid
- region
- charity_count
List of all regions:
Get regions by id - for example 4:
