There are six parameters available specifically to this API:
There are six parameters available specifically to this API:
Parameter | Description |
---|---|
APIKey (required) | Request a unique APIKey. You may also use DONORSCHOOSE for testing purposes. If you don’t have a unique API key, location information or classroom photos may be omitted to protect school privacy. |
callback (optional) | If you wish to wrap your response in a callback function, include the name here.You should make your callback static, as it will improve caching and in turn performance. (Many AJAX frameworks will make the callback a random string unless otherwise specified so you’ll be overriding that default behavior.)Also be sure to enable any caching options (eg. set the cache param to True in jQuery) or else some frameworks will append a timestamp to each JSON request to prevent caching. |
index (optional) | By default, the start index of the result set is 0; for example, by setting index=10 and max=10, you can return rows 10-19. |
max (optional) | By default, the maximum number of projects returned is 10; you can request up to 50 rows at a time. |
showSynopsis (optional) | To show the synopsis for each project listing set this to true. |
showFacetCounts (optional) | To show facet counts set this to true. They will appear after the project listings. See the Facet Counts section in JSON Responses for more details. |
In addition, please include at least one search parameter:
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:
Optional parameters:
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
Music & The Arts Performing Arts Visual Arts Music |
subject1=-1 subject1=1 subject1=11 subject1=12 |
Health & Sports Sports Health & Wellness Nutrition Gym & Fitness |
subject2=-2 subject2=2 subject2=27 subject2=28 subject2=29 |
Literacy & Language Literacy Literature & Writing Foreign Languages ESL |
subject6=-6 subject6=10 subject6=3 subject6=22 subject6=25 |
History & Civics History & Geography Civics & Government Economics Social Sciences |
subject3=-3 subject3=9 subject3=13 subject3=14 subject3=15 |
Math & Science Health & Life Science Applied Science Environmental Science Mathematics |
subject4=-4 subject4=4 subject4=6 subject4=7 subject4=8 |
Special Needs | subject7=-7 |
Applied Learning Early Development Community Service Character Education College & Career Prep Extra Curricular Parental Involvement Other |
subject5=-5 subject5=18 subject5=21 subject5=26 subject5=16 subject5=17 subject5=20 subject5=19 |
Some Received Projects that have already received partial donations | partiallyFunded=yes |
None Yet Projects that haven’t yet received a donation | partiallyFunded=no |
High Level of Poverty Projects from high need and high poverty schools (40% or more students receive free lunch) | highLevelPoverty=true |
Highest Level of Poverty Projects from highest need and highest poverty schools (65% or more students receive free lunch) | highestLevelPoverty=true |
Never Before Funded Projects from teachers that have never had a project funded… yet | teacherNotFunded=true |
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.
Books | proposalType=1 |
Technology | proposalType=2 |
Supplies | proposalType=3 |
Trips | proposalType=4 |
Visitors | proposalType=5 |
Other | proposalType=6 |
Trips & Visitors | proposalTypeCombo=Trips+%26+Visitors |
Supplies | proposalTypeCombo=Supplies |
Grades PreK-2 | gradeType=1 |
Grades 3-5 | gradeType=2 |
Grades 6-8 | gradeType=3 |
High School | gradeType=4 |
Adult Ed | gradeType=5 |
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
Teach For America | teacherType=1 |
Charter School | schoolType=1 |
Magnet School | schoolType=4 |
Year Round School | schoolType=5 |
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.
State or sub-state region | State or metro code |
Alabama | AL |
Alaska | AK |
Arizona | AZ |
Arkansas | AR |
California | CA |
Colorado | CO |
Connecticut | CT |
Delaware | DE |
Florida | FL |
Georgia | GA |
Hawaii | HI |
Idaho | ID |
Illinois | IL |
Indiana | IN |
Iowa | IA |
Kansas | KS |
Kentucky | KY |
Louisiana | LA |
Maine | MN |
Maryland | MD |
Massachusetts | MA |
Michigan | MI |
Minnesota | MN |
Mississippi | MS |
Missouri | MO |
Montana | MT |
Nebraska | NE |
Nevada | NV |
New Hampshire | NH |
New Jersey | NJ |
New Mexico | NM |
New York | NY |
North Carolina | NC |
North Dakota | ND |
Ohio | OH |
Oklahoma | OK |
Oregon | OR |
Pennsylvania | PA |
Rhode Island | RI |
South Carolina | SC |
South Dakota | SD |
Tennessee | TN |
Texas | TX |
Utah | UT |
Vermont | VT |
Virginia | VA |
Washington | WA |
Washington D.C. | DC |
West Virginia | WV |
Wisconsin | WI |
Wyoming | WY |
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.
Urgency shows projects with higher urgency at the top | sortBy=0 |
Poverty shows projects from schools with the highest levels of poverty at the top | sortBy=1 |
Cost shows projects with the lowest cost to complete at the top | sortBy=2 |
Popularity shows projects with higher numbers of donors at the top | sortBy=4 |
Expiration shows projects that are closest to expiring | sortBy=5 |
Newest shows projects that were created most recently | sortBy=7 |
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