JSON Responses

Let's take a look at the fields and elements you will receive in your JSON response. Here's an example:
{"searchTerms":"Art & Music",
"searchURL":"https://www.donorschoose.org/donors/search.html?subject1=-1&utm_source=api&utm_medium=feed&utm_content=searchlink&utm_campaign=DONORSCHOOSE",
"totalProposals":"1694?,
"index":"0?,
"max":"10?,
"proposals":[

{
"id":"259649?,
"proposalURL":"https://www.donorschoose.org/donors/proposal.html?id=259649&utm_source=api&utm_medium=feed&utm_content=bodylink&utm_campaign=DONORSCHOOSE",
"fundURL":"https://secure.donorschoose.org/donors/givingCart.html?proposalid=259649&donationAmount=45&utm_source=api&utm_medium=feed&utm_content=fundlink&utm_campaign=DONORSCHOOSE",
"imageURL":"",
"title":"Self Critique",
"shortDescription":"My students need a camcorder to evaluate their speeches and debates. Since the self is the most difficult critic, my skilled orators need the opportunity to view themselves in order to see what others see.",
"fulfillmentTrailer":"My students need a camcorder to evaluate their speeches and debates. ",
"percentFunded":"88?,
"costToComplete":"52.94?,
"matchingFund":{"matchingKey":"","name":"","logoURL":"","faqURL":"","amount":"0.0?},
"totalPrice":"453.0?,
"teacherId": "259649",
"teacherName":"Ms. H",
"gradeLevel":{"id":"Grades 9-12?,"name":"4?},
"povertyLevel":"High Poverty",
"schoolName":"West Charlotte High School",
"city":"Charlotte",
"state":"NC",
"zip":"28216?,
"subject":{"id":"1?,"name":"Performing Arts","groupId": "1"},
"resource":{"id":"2?,"name":"Technology"},
"expirationDate":"2009-07-29?
},
...

]}

All fields are returned as XML-escaped strings, except URLs, which are not XML-escaped. Please perform a cast to compare dates, dollar amounts, and percentages.

If you wish to wrap your JSON object in a callback function, include "callback" in your request query string (see API Specific Requests). 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.

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

* To protect schools' privacy, this field will be empty if thank-you photos are present and you do not have a unique API key.
** If data for a field is not provided for given project, the field will be empty in the JSON response.
*** To protect schools' privacy, this array will be empty if you search by teacher, school, city, zip code, county, community, or latitude/longitude and you do not have a unique API key.

The thankYouAssets?interimThankYou, photos, resultsLetter?are uploaded to our site by teachers separately and over time, so a completed project might have all of them, none, or only some.

Check out https://www.donorschoose.org/donors/search.html?historical=true&max=25 and you'll to see that projects display differently based on which thankYouAssets are available.

Similarly, if you eyeball this JSON response, https://api.donorschoose.org/common/json_feed.html?historical=true&max=25&APIKey=[YOUR_API_KEY], you'll see that the various projects have different combinations of thankYouAssets available.

Typically the interimThankYou arrives first, then the photos and resultsLetter arrive a few wks later. So the display logic on our site is:

• If no thankYouAssets are assets available, display the project just like a live project, but with the Completed label and graphic.
• If only interimThankYou is available (called "Thank You Letter" on our front-end), display like above plus the interimThankYou appended in place of where we'd usually show the number of donors and most recent donor msg.
• When photos are available, show them in place of the shortDescription and fulfillmentTrailer.
• When resultsLetter is available (called "Impact Letter" on our front-end), show it in place of the interimThankYou.

For safety reasons, API keys must be specially provisioned to access these photos. If you want access to these photos, let us know when you get in touch to request your API key.

An example of a JSON response with facet counts:

{
...
"proposals":[...],
"facetCounts":{
"location":{"state":{"Illinois":24,"South Carolina":82,"Rhode Island":12,"New Mexico":0,"California (South)":78,"Alabama":0,"Florida":43,"New Hampshire":1,"Massachusetts":17,"Tennessee":12,"Louisiana":34,"Maryland":14,"California (North)":81,"Ohio":24,"West Virginia":2,"Idaho":6,"Virginia":25,"Mississippi":23,"Texas":55,"Vermont":1,"Kansas"0,"Michigan":17,"New Jersey":16,"Colorado":7,"Pennsylvania":52,"Maine":9,"Illinois (Chicago)":67,"Arkansas":6,"Missouri":22,"New York (City)":132,"Iowa":8,"Oregon":15,"North Dakota":2,"Indiana":51,"Washington D.C.":12,"Wisconsin":24,"Nevada":59,"Minnesota":7,"Washington":22,"Hawaii":5,"Connecticut":22,"Montana":2,"Oklahoma":57,"North Carolina":132,"Arizona":14,"New York (State)":54,"Kentucky":15,"Alaska":6,"Georgia":24,"Utah":18,"Nebraska":1}},
"subject":{"Health, Sports, & Wellness":15,"STEM":148,"Other Areas":360,"Art & Music":{"Performing Arts":386,"Visual Arts":807,"Music":439},"Literacy & History":0},
"proposalType":{"Supplies":631,"Books":93,"Trips":1,"Other":127,"Technology":575},
"costToComplete":{"$1000-above":114,"$100-$200?:130,"$200-$1000?:1142,"$0-$99?:41},
"partiallyFunded":{"Some Received":558,"None Yet":869},
"teacherNotFunded":645,
"gradeType":{"Grades 9-12?:280,"Grades PreK-2?:406,"Adult Ed":6,"Grades 3-5?:482,"Grades 6-8?:253},
"teacherType":{"NY Teaching Fellow":9,"Teach For America":18},
"schoolType":{"NLNS":23,"Year Round":114,"Charter":84,"Magnet":124}
}
}

Different facet categories are treated differently. Examples follow:

The latitude and longitude values accompanying each project looks like:

...
"zip":"89101-2703?,
"state":"NV",
"latitude":"36.176514000000000?,
"longitude":"-115.122437000000000?,
"subject":{"id":"11?,"name":"Visual Arts","groupId": "1"},
...

If you add the &concise=true parameter to your JSON request, the JSON response will only include 4 fields demonstrated below, which greatly accelerates the speed with which we can generate and transmit large result sets to your app:

...
{"id":"358311?,
"latitude":"40.706825?,
"longitude":"-73.920003?,
"title":"Inkless Printers Need Toner!!"},

{"id":"394415?,
"latitude":"40.687007?,
"longitude":"-73.878525?,
"title":"Don't Stop Believing...Hold on to Your Reading!"},

{"id":"399739?,
"latitude":"40.699193?,
"longitude":"-73.90397?,
"title":"Help Give 3rd Grade ESL Students an Invaluable Research Tool"},
...

You can then request full details as-needed on a per-project basis.

If you add the &description=true parameter along with &concise=true to your JSON request, the JSON response will include 5 fields in addition to the concise fields:

...
{"id": "358311",
"proposalURL": "https://www.donorschoose.org/donors/proposal.html?id=358311",
"latitude": "40.706825",
"longitude": "-73.920003",
"imageURL": "http://s3.donorschoose.net/donorschoose-storage/dc_prod/images/user/small/u276967_sm.jpg",
"shortdescription": "I love being able to hang up my student's work around the room and they love being able to take their work home to show their parents. Since our school does not have money to buy toner cartridges, the students have not been able to complete work on the computers because...",
"costToComplete": "255.71",
"schoolName": "Jhs 162 Willoughby",
"city": "Brooklyn",
"state": "NY",
"title": "Inkless Printers Need Toner!!"},
...