Response example

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":"http://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":"http://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=&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",
	"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 strings; 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.)

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

Project Listing Overview Elements

Per-Project Listing Fields

** If data for a field is not provided for given project, the field will be empty in the JSON response.

Completed Projects' Thank-You Assets

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 http://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-- http://api.donorschoose.org/common/json_feed.html?historical=true&max=25&APIKey=DONORSCHOOSE --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.

Facet Counts

An example of a JSON response with facet counts:

{
...
"proposals":[...],
"facetCounts":{
"location":{"state":{"Illinois":24,"South Carolina":82,"Rhode Island":12,"New Mexico":1,"California (South)":78,"Alabama":9,"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":5,"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":15,"Math & Science":148,"Other Areas":360,"Art & Music":{"Performing Arts":386,"Visual Arts":807,"Music":439},"Literacy & History":513},
"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,
"resourceUsage":{"Essential":568,"Enrichment":859},
"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}
}
}

If a count is not specified, that means it's zero.

Different facet categories are treated differently. Examples follow:

Location

    "location":{"state":[["CA","California",2265],[412,"Nevada",311], ..., [241,"Idaho",78]]}

If state=CA in the search parameters:

"location":{
  "city":[[218,"Albertville",19],[212,"Abbeville",4], ... [598,"Woodstock",3]],
  "county":[[63,"Autauga",2],[68,"Bullock",1], ... [120,"Shelby",1]],
  "district":[[475,"Anniston City School District",1], ... [15370,"Boaz City School System",3]]
}

"location":{
  "school":[[15847,"Dutton Elementary School",1],[13451,"Woodville High School",1], ... 
[14561,"Paint Rock Valley High School",2]]
}

If community=540:2 and showZeroFacetCountsForSchools=true in the search parameters:

(The difference between the latter and the former being that ALL schools are listed in the response, even those with zero live projects.)

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

...
{"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"},
...