JSON Requests

Note that search parameters are frequently updated; for the most up-to-date options, use DonorsChoose.org’s Search Projects functionality as a starting point.

Keyword Search

Example:

https://api.donorschoose.org/common/json_feed.html?keywords=”Canoga+Park”&APIKey=DONORSCHOOSE

In this example, we are searching for the phrase “Canoga Park.”  To search for a phrase, enclose it in quotes. It gets a list of projects where the keyword search matches any of the following fields:

• id
• title
• synopsis (full length project essay; not returned in JSON)
• short description
• fulfillment trailer
• school name
• teacher’s first name (not returned in JSON)
• teacher’s last name (only initial returned in JSON)
• city
• county (not returned in JSON)
• district (not returned in JSON)
• ward/neighborhood (not returned in JSON)
• state (e.g. TX)
• zip (not returned in JSON)
• subject name

Example of searching for all Art & Music projects:
https://api.donorschoose.org/common/json_feed.html?subject1=-1&APIKey=DONORSCHOOSE

Example of searching for only Music projects: 
https://api.donorschoose.org/common/json_feed.html?subject1=12&APIKey=DONORSCHOOSE

You can also search for subjects using keyword search. Here’s an example of Music projects using keyword search:
https://api.donorschoose.org/common/json_feed.html?keywords=Music&APIKey=DONORSCHOOSE

Example: costToCompleteRange=0+TO+400

These values include the 15% optional donation to support the work DonorsChoose.org does to engage teachers, acquire donors, and generally run our operation.

Most of our projects are thought of and created by teachers, but we also have “student-led” projects that involve more input from the students. To see only student-led projects, set the studentLed parameter to true. To see only teacher-led projects, set it to false. If this parameter isn’t proved, you’ll receive a mixture of student-led and teacher-led projects.

For example, this lists all student-led projects: https://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE&studentLed=true

Examples:
id=242352
id=252344,773543,453457

If you already know the IDs of the project or projects you’re looking for, you can find information about those particular projects with this parameter. You can either provide a single project ID, or a comma-delimited list of them. If this parameter is specified, the historical parameter is ignored. Both active and historical projects with the given id(s) will be returned.

Example: challengeId=18369

Please note that, in contrast to the challenge page (https://www.donorschoose.org/donors/viewChallenge.html?id=18369), only projects that still need funding will be included in the JSON feed.

Example: matchingId=6

Please use the “Match Offers” filter on our Search Projects page to get the matching grant value you need.

To search by state code (e.g. TX) you can either do a keyword search or use the state parameter (e.g. state=TX).
You cannot search by metro code. We’ve included it as a reference as it might be helpful for geo-targeting scenarios since many IP-to-geo services will output metro codes.

You can search by zip code using the keyword search field.

Example: community=7%3a1
Please use the “Community” filter on our Search Projects page to get the community values you need. If you cannot find a particular city, county, or district through the Search Projects functionality, please contact us for help.
In some cities you can search by ward (e.g. Washington DC) or neighborhood (e.g. New York City, Chicago). Please note that you can also use a keywords search to find projects in any community. Finally, you can use the cityName parameter for city and the countyName parameter for county.

Example: school=472
Please use the Search Projects functionality to identify a specific school. Also note that you can search by school name using a keywords search.

The &historical=true parameter returns completed projects only. Without adding that parameter, the default behavior is to always return projects in need of funding.

An example of already-completed yoga-related projects: https://api.donorschoose.org/common/json_feed.html?keywords=yoga&historical=true&APIKey=DONORSCHOOSE

Geo: Lat/Long Data

You will get latitude and longitude values accompanying each project in all JSON responses. No additional request parameters are needed to prompt the inclusion of the lat/long data.

Geo: “Bounding Box” Searches

You can specify the northwest and southeast corners of a geographic area to request projects posted from classrooms located within the specified geographic “bounding box.”

Specify the NW point using the parameters nwLat and nwLng. Specify the SE point using seLat and seLng.

An example of projects within the area bounded by the NW point 40.776104/-73.920822 and the SE point 40.632437/-73.797226: https://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE&nwLat=40.776104&nwLng=-73.920822&seLat=40.632437&seLng=-73.797226

Geo: “Center + Distance” Searches

You can also specify the center plus a radius of a geographic area to request projects posted from classrooms located within the specified circular geographic region.

Specify the center point using the parameters centerLat and centerLng. Specify the radius using radius.

An example of projects within the area within 50 miles of the point 40.776104/-73.920822: https://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE¢erLat=40.776104¢erLng=-73.920822&radius=50

Geo: “Projects Near Me” Searches

You can also specify the center without a radius and the system will return at least 25 results near the specified point (if there are 25 projects that match the other criteria in the search). Note that if “max” is not specified then there will be only 10 projects returned.

Specify the center point using the parameters centerLat and centerLng. Leave out the “radius” parameter.

An example of projects near the point 40.776104/-73.920822: https://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE¢erLat=40.776104¢erLng=-73.920822

If you are plotting potentially many points on a map, we recommend you use add the &concise=true parameter to your JSON request. This feature reduces the amount of per-project info returned in the JSON response to only 4 fields which greatly accelerates the speed with which we can return you large result sets.

Including the &concise=true parameter also raises the per-request maximum to 1,000 projects which is especially useful for plotting points on a map.

An example of (up to 1,000) Art & Music projects the concise format: https://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE&subject1=-1&concise=true

An example of (up to 1,000) projects within the area bounded by the NW point 40.776104/-73.920822 and the SE point 40.632437/-73.797226: https://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE&nwLat=40.776104&nwLng=-73.920822&seLat=40.632437&seLng=-73.797226&concise=true

We’ll first need to enable your API key for extra large responses. Get in touch with us to get an enabled API key.

If you only want to retrieve projects that were added to the site before or after a certain date, you can use the newSince and olderThan parameters. They each take a date/time represented as milliseconds since epoch.

An example of projects posted since midnight GMT on August 20, 2014: https://api.donorschoose.org/common/json_feed.html?APIKey=DONORSCHOOSE&newSince=1408492800000