API Documentation

Introduction

The Charity Navigator API is a RESTful API that provides access to a subset of the data available in the Charity Navigator database. The API provides methods for accessing data on:

Charity Filings
Charity Ratings
Charity Financials
Human development indicators

Live server

https://api.charitysense.org/

REST API Endpoints

GET /question

This endpoint takes in a natural language query ("e.g. Show me the best charities for Africa") and returns a JSON object that specifies the appropriate parameters for /charities, /indicator, /event that tries to answer that query.

GET /charities

This endpoint retrieves a list of charities with optional query parameters.

Optional query parameters

Parameter	Description	Default
`search`	Search for charities by name or description (optional).
`limit`	Limit number of returned charities (optional, default=20)	20
`skip`	Skip number of returned charities (optional, default=0)	0
`map_coordinates`	Filter charities by geographical location using either a country or a bounding box defined by latitude and longitude coordinates.
`sort_by`	Sort the list of charities by a given field. Possible values are "rating", "name", "expenses", "revenues", "assets", "liabilities". (optional, sort_by=rating)	rating
`rating_gt`	Filter charities with a rating greater than a specified value. (optional, default=0)	0
`assets_gt`	Filter charities with assets greater than a specified value. (optional, default=None, range: 0-5)	None
`assets_lt`	Filter charities with assets less than a specified value. (optional, default=None)	None
`liabilities_gt`	Filter charities with liabilities greater than a specified value. (optional, default=None)	None
`liabilities_lt`	Filter charities with liabilities less than a specified value. (optional, default=None)	None
`expenses_gt`	Filter charities with expenses greater than a specified value. (optional, default=0)	0
`expenses_lt`	Filter charities with expenses less than a specified value. (optional, default=None)	None
`eins`	Filter charities by a list of EINs (optional).
`affiliation`	Filter charities by religious affiliation, must be one of the following: Any, None, Christianity, Islam, Hinduism, Buddhism, Sikhism, Judaism, Bahai
`nonprofit`	Only return entities that are charitable, which excludes foundations, insurance companies, and trusts among others. (optional, default="true")	true

Example

GET /charities?search=fire&limit=10&skip=10&map_coordinates=usa&sort_by=rating&rating_gt=4&expenses_gt=1000000&eins=123456789,987654321

This example retrieves a list of at most 10 charities related to fire, skipping the first 10 records, located in the USA, with a rating greater than 4, expenses greater than $1,000,000, and having EINs of 123456789 and 987654321. The list is sorted by rating.

GET /charities/{ein}

Retrieve a single charity by EIN (Employer Identification Number).

Optional query parameters

Parameter	Description	Default
`year`	Retrieve charity data from given year. If omitted, "latest" is assumed	latest

Example

GET /charity/752882187?year=2019

This example retrieves the charity with the EIN 752882187 from year 2019.

GET /indicators

Retrieve a list of indicators.

Optional query parameters

Parameter	Description
`search`	Search for charities by name or description.
`limit`	Limit number of returned indicators.

Example

GET /indicators?search=electric&limit=5

This example retrieves a list of indicators related to electricity and returns 5 topics. When no parameters are provided, return all indicators and topics

GET /indicator/{name}

Retrieve a single indicator by name.

Optional query parameters

Parameter	Description	Default
`year`	Search for indicators by year (default `latest`).	latest

Example

GET /indicator/'GNI per capita, PPP (current international $)'?year=latest

This example retrieves the indicator with the name GDP.

GET /events

Retrieve a list of events

Example

GET /events

Returns a list of valid event tags

GET /event/{tag}

Return GeoJSON map data for a given event

Required query parameter

Parameter	Description
`tag`	Retrieve events by tag, such as 'flood' or 'earthquake'

Example

/event/volcano

This example retrieves volcano map data