You're on track to get doubled donations (and unlock a reward for the colleague who referred you). Keep up the great work!
Take credit for your charitable giving! Check out your tax receipts
Donate
To use your $50 gift card credits, find a project to fund and we'll automatically apply your credits at checkout. Find a classroom project
Menu
Skip to main content

Help teachers & students in your hometown this season!
Use code HOME at checkout and your donation will be matched up to $100.

Your school email address was successfully verified.

JSON Requests

There are six parameters available specifically to this API:

API Specific Parameters
Parameter Description
APIKey (required) Your unique API Key
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.
includeResources (optional) To include the resources requested by the teacher, set this to true.

In addition, please include at least one search parameter:

Search Parameters

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=[YOUR_API_KEY]

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

Optional parameters:

Subject

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

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

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=[YOUR_API_KEY]

Music & The Arts
Performing Arts
Visual Arts
Music		 subject1=-1
subject1=1
subject1=11
subject1=12
Health, Sports, & Wellness
Team Sports
Health & Wellness
Nutrition
Gym & Fitness
Mental Health		 subject2=-2
subject2=2
subject2=27
subject2=28
subject2=29
subject2=33
Social Studies
History & Geography
Civics & Government
Economics
Social Sciences		 subject3=-3
subject3=9
subject3=13
subject3=14
subject3=15
STEM
Science
Engineering & Technology
Climate & The Environment
Mathematics		 subject4=-4
subject4=4
subject4=6
subject4=7
subject4=8
Life Skills
College & Career Prep
Clubs & Activities
Early Development
Community Service
Financial Literacy
Social Emotional Learning		 subject5=-5
subject5=16
subject5=17
subject5=18
subject5=21
subject5=30
subject5=32
Literacy & Language
Literature & Writing
Literacy
World Languages
English Language Learning		 subject6=-6
subject6=3
subject6=10
subject6=22
subject6=25
Students with Disabilities subject7=-7
Warmth, Care & Hunger subject8=-8
Racial Justice & Representation subject9=-9

Special Categories
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

Cost to Complete Range

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.

Resource Type
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

Grade Level
Grades PreK-2 gradeType=1
Grades 3-5 gradeType=2
Grades 6-8 gradeType=3
High School gradeType=4
Adult Ed gradeType=5

Project Type

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=[YOUR_API_KEY]&studentLed=true

Teacher Type
Teach For America teacherType=1

School Type
Charter School schoolType=1
Magnet School schoolType=4
Year Round School schoolType=5

Project ID

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.

Challenges and Giving Pages

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.

Matching Grant

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 regions
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.

Zip code

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

Community (city, county, district, or special)

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.

School

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.

Sorting Options
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

Completed

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=[YOUR_API_KEY]

Geo Parameters

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=[YOUR_API_KEY]&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=[YOUR_API_KEY]?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=[YOUR_API_KEY]?erLat=40.776104?erLng=-73.920822

Large Result Set

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=[YOUR_API_KEY]&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=[YOUR_API_KEY]&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.

Project Creation Date

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=[YOUR_API_KEY]&newSince=1408492800000

Supporting teachers and students since 2000

DonorsChoose makes it easy for anyone to help a classroom in need. Public school teachers from every corner of America create classroom project requests, and you can give any amount to the project that inspires you.

We've earned the highest possible ratings from Better Business Bureau, Charity Watch, Charity Navigator, and Guidestar.