JSON Responses - Data for Education
15137
page-template-default,page,page-id-15137,page-child,parent-pageid-15126,ajax_fade,page_not_loaded,,side_area_uncovered_from_content,qode-theme-ver-10.0,wpb-js-composer js-comp-ver-4.12,vc_responsive

JSON Responses

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

Project Listing Overview Elements
searchTerms A text description of your search criteria, such as “Art & Music”
searchURL A url which can be used to link back to DonorsChoose.org’s search results page, such as https://www.donorschoose.org/donors/search.html?subject1=-1&utm_source=api&utm_medium=feed&utm_content=searchlink&utm_campaign=DONORSCHOOSE
totalProposals Total number of projects found
index Starting index of project rows returned
max Number of project rows returned; default is 10, capped at 50
proposals An array of project listings; per-project fields are described in the table below; will be returned empty if there are no project listings matching the criteria in the request

Per-Project Listing Fields
Field Type Description Always provided?**
id long Unique project ID # Yes
proposalURL string Permalink to project details page, e.g. https://www.donorschoose.org/donors/proposal.html?id=259649&utm_source=api&utm_medium=feed&utm_content=bodylink&utm_campaign=DONORSCHOOSE Yes
fundURL string Permalink to commence donating to a project, e.g. https://secure.donorschoose.org/donors/givingCart.html?proposalid=259649&donationAmount=45&utm_source=api&utm_medium=feed&utm_content=fundlink&utm_campaign=DONORSCHOOSE. You must supply a value for the donationAmount parameter. The default is $45. Yes
imageURL string Link to teacher-provided classroom photo, either a GIF or JPG with a max width of 210 px, eg. https://www.donorschoose.org/images/user/uploads/small/12220/u12220_sm.jpg. As a safety precaution, classroom photo is not provided if the request includes county, district, community, city, or school search parameters. No
title string Project title Yes
shortDescription string Short project summary (excerpted from the project essay) Yes
fulfillmentTrailer string Short description of project material needs Yes
synopsis string Unabridged project essay. Paragraph ends are delimited with “<br/><br/>”. No
percentFunded integer Percent of funding project has already received (between 1 and 100) Yes
numDonors integer Number of donors that gave to the project Yes
costToComplete double Remaining amount needed to fully fund the project. The amount includes the 15% optional donation to support the work DonorsChoose.org does to engage teachers, acquire donors, and generally run our operation. Yes
totalPrice double Total cost of the project Yes
freeShipping boolean Whether or not resources were free to ship Yes
teacherId long Teacher’s ID number Yes
teacherName string Teacher’s title plus last initial or last name, depending on the teacher’s settings (e.g. Mr. S or Mr. Smith) Yes
gradeLevel
id
name
integer
string
Classroom grade level Yes
povertyLevel string Poverty level refers to the percentage of students at a given school who qualify for free or reduced lunch, which is considered a measure of economic need. Yes
schoolName* string Name of the School No
city* string City the school is in No
zip* string Zip code of the school No
state string Two letter abbreviation, e.g. CA for California Yes
subject
id
name
groupId
integer
string
integer
Primary subject area Yes
resource
id
name
integer
string
Type of classroom materials requested, e.g. Classroom Supplies, Class Trips, Classroom Visitors Yes
expirationDate date Project expiration date Yes
matchingFund matchingKey
name
logoURL
faqURL
amount
description
stringstring

string

string

double

string

If available, the following fields are provided:Matching sponsor’s internal identifier

Matching sponsor’s name

URL of Matching sponsor’s logo image

URL of popup summary of sponsor’s matching terms

Amount contributed by sponsor when percentFunded reaches 50%

Matching sponsor’s description

No
fundingStatus string Either “needs funding” or “funded” No
thankYouAssetsinterimThankYou

photos***

resultsLetter

stringarray

string

If available, the following fields are provided:Interim Thank You Letter

Photos (an array of URL’s)

Results Letter

No

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

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

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.

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”: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”:15,”Math & Science”: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:

Location

“location”:{“state”:[[“CA”,”California”,2265],[412,”Nevada”,311], …, [241,”Idaho”,78]]}
In [“CA”,”California”,2265], “CA” is the state code, “California” is the state name, and 2265 is the project count.
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]]
}

If community=540:2 in the search parameters:
“location”:{
“school”:[[15847,”Dutton Elementary School”,1],[13451,”Woodville High School”,1], …
[14561,”Paint Rock Valley High School”,2]]

}

Subject

“subject”:{“Health & Sports”:1231,”Math & Science”:1373,”Other Areas”:3594,”Art & Music”:1782,”Literacy & History”:5232}

If subject1=-1 in the search parameters:

“subject”:{“Health & Sports”:14,”Math & Science”:137,”Other Areas”:359,”Art & Music”:{“Performing Arts”:381,”Visual Arts”:827,”Music”:448},”Literacy & History”:523}

If subject1=1 in the search parameters:

“subject”:{“Health & Sports”:8,”Math & Science”:16,”Other Areas”:80,”Art & Music”:{“Visual Arts”:34,”Music”:155},”Literacy & History”:128}

Note that “Performing Arts” is missing in the above example.

Resource

“proposalType”:{“Books”:104,”Technology”:579,”Supplies”:642,”Trips”:1,”Visitors”:2,”Other”:126}

If proposalType=1 in the search parameters:

“proposalType”:{}

Facet counts for Cost to Complete (key: costToComplete), Donations (key: partiallyFunded), and Grade Level (key: gradeType) follow the same scheme.

Never Before Funded

“teacherNotFunded”:1728

If teacherNotFunded=true in the search parameters, this field won’t be shown.

School Affiliation

“schoolType”:{“Charter”:519,”Magnet”:969,”Year Round”:758,”NLNS”:174}

If schoolType=1 in the search parameters:

{“Magnet”:7,”Year Round”:45,”NLNS”:30}

Facet counts for Teacher Affiliation (key: teacherType) follow the same scheme.

Field lengths for classroom projects
Field JSON field Avg length (chars) 95th percentile length (chars) Search UX (example) Homepage UX (example) Project UX 
(example)
Titles title 29 54 Never truncated Never truncated Never truncated
Short descriptions shortDescription 263 436 Truncated >200 chars Never truncated Never truncated
Resource summaries fulfillmentTrailer 106 224 Truncated >100 chars Truncated >200 chars Never truncated
Fully essay synopsis 1,544 2,617 Not shown Not shown Truncated at 300 chars, shown in entirety via  “More” link

Image dimensions
Image JSON field Actual size Search UX Project UX
Classroom photo imageURL Max width of 210, but often taller Max width of 155 Full size
Thank-you photo (small) thankYouAssets.photos 183 x 183 (max) 130 x 100 (scaled down) (example) Full size (example)

Geo Data

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”},

Concise results format

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.

Concise results format with short description

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!!”},