The best way to get to know our project listings API is to first play around with our front-end project search functionality. Reason being that our project listings API offers programmatic access to the same exact functionality and information as our front-end search.
So check-out our front-end project search functionality. Note...
- The project listings info: title, photo, location, description, amount needed, etc.
- You can click into a project and access even more info about it.
- All the ways you can search for projects, using the provided filters such as location, subject, and keyword.
- Under "More Criteria" you'll find a bunch more filters such as resource type, grade level, whether the project is eligible for any match offers, whether the project already has donations, etc, etc.
Once you have a feel for our front-end project search, constructing JSON requests should come more easily. In fact, it's made especially easy since the request parameters for front-end search and the JSON API are nearly identical! Just a few tweaks to the URL of your front-end search results will turn it into a JSON request for the same projects.
For example:
This is the front-end search results URL for classroom projects in Charlotte, North Carolina: https://www.donorschoose.org/donors/search.html?state=NC&community=10007:3
...and this is the JSON request for the same project listings: https://api.donorschoose.org/common/json_feed.html?state=NC&community=10007:3&APIKey=[YOUR_API_KEY]
The request is aimed at a different endpoint (https://api.donorschoose.org/common/json_feed.html?) and an API key has been tacked onto the end as an additional parameter (&APIKey=[YOU_API_KEY]), but the request arguments are otherwise the same.
Heads up that the first 70 lines of the response are blank so if you're viewing the response in your browser, you'll likely have to scroll a bit to get to the good stuff. (We know this is a bit annoying and hope to fix it soon.)
Similarly, this is the front-end search results URL for Health, Sports, & Wellness-related classroom projects from charter high school classrooms: https://www.donorschoose.org/donors/search.html?gradeType=4&subject2=-2&schoolType=1
...and this is the JSON request: https://api.donorschoose.org/common/json_feed.html?gradeType=4&subject2=-1&schoolType=1&APIKey=[YOUR_API_KEY]
A front-end keyword search for already-completed yoga-related projects: https://www.donorschoose.org/donors/search.html?keywords=yoga&historical=true
...and the JSON request: https://api.donorschoose.org/common/json_feed.html?keywords=yoga&historical=true&APIKey=[YOUR_API_KEY]
You get the picture!
So if you're wondering whether you can request certain specific types of projects via the API, try to filter for just those kinds of projects using the front-end search UX. If you can do it there, you can almost certainly do it via the API.
If you're wondering whether you can get a specific project attribute from the API, check out the project listings and project details screens via the front-end search UX first.
Once you've got a general handle on what you can request from the API and the kind of information you'll get back, you can dive into the full details of how API requests and responses can be structured.