Help

DonorsChoose.org Classroom Project Listings API

The DonorsChoose.org Classroom Project Listings API allows developers to add DonorsChoose.org's classroom projects to their website or application using their own search criteria, page layout and branding. In a nutshell, a developer can make an HTTP request—constructed very similarly to a regular DonorsChoose.org front-end Search Projects functionality—and receive classroom project listings in a JSON response.

Table of Contents

• If you only read one thing...
• What is JSON?
• How can I receive a unique API key?
• What can I include in my HTTP request?
• How can I read the JSON response?
• APPENDIX A: Request Parameters
• APPENDIX B: Facet Counts
• APPENDIX C: Sample Requests
• How can I contact the DC.org tech team with any questions about using the API?

If you only read one thing...

If you choose to make use of this API, please take a minute to subscribe to our API email list. This will enable us to notify API users of important updates and service advisories. We expect to email our list less than once a month and you can unsubscribe at any time.

What is JSON?

JSON (JavaScript Object Notation) is a simple, lightweight data format that represents arrays and key/value pairs, and is often used in place of XML. While JSON was originally formulated to take advantage of Javascript's eval function, libraries are now available for Java, PHP, Actionscript, and many others. You can learn more and download code here: http://www.json.org/

How can I make an HTTP request?

The easiest way to build your first request is to start by searching for projects on our site. For example, if you'd like to see a list of Arts & Music projects, the search results page address looks like this:

• http://www.donorschoose.org/donors/search.html?subject1=-1

To view the same list in JSON format, simply change the URL like so:

• http://api.donorschoose.org/common/json_feed.html?subject1=-1&APIKey=DONORSCHOOSE

Notice that in addition to changing the sub-domain from www. to api. and the URI from /donors/search.html to /common/json_feed.html, you will need to include an API Key on the query string.

How can I receive a unique API key?

Feel free to use the default API key "DONORSCHOOSE" for evaluative or testing purposes. However, during periods of high web traffic, we may temporarily disable API requests using the default key. This is to ensure that maximum server resources are available both to front-end users of DonorsChoose.org and those developers using our API in "production" integration environments. When the default key is temporarily disabled, an empty project set and 403 header is returned.

To ensure API connectivity for your site or application, please request a unique API key from us via email: apikey (at) donorschoose (dot) org. Please include your contact information, as well as your best estimate of the daily and peak number of requests your app will make against the API.

We intend to quickly approve any API key request that doesn't violate our User Agreement and we'll only contact you directly if something comes up down the line. We will use the traffic estimates you provide for capacity planning purposes.

If you'd also like to receive news about the latest updates and improvements to our API, please join our user group at http://tech.groups.yahoo.com/group/donorschoose-api/. We expect to email our list less than once a month.

What can I include in my HTTP request?

We recommend that you use our front-end Search Projects functionality at DonorsChoose.org as a starting point for building out your requests. If you would like to explore the search criteria available to you in more depth, refer to the appendix below.

In addition, the following query string parameters are available:

How can I read the JSON response?

An example of a JSON response:

{"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&zone=0",
	"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",
	"zone":{"id":"301","name":"North Carolina"},
	"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.

Please note: If you wish to wrap your JSON object in a callback function, include "callback" in your request query string (see "What can I include in my HTTP request?" above).

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.

APPENDIX A: Request Parameters

http://api.donorschoose.org/common/json_feed.html

API Specific Parameters

There are six parameters available specifically to this API:

In addition, please include at least one search parameter, as described below.

Search Parameters

Please note that search parameters are frequently updated; for the most up-to-date options, please use DonorsChoose.org's Search Projects functionality as a starting point.

Keyword Search

• 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)
• statecode (e.g. tx)
• zip (not returned in JSON)
• zone name
• subject name

Project Id

Example: id=259649

Returns data for a specific project.

Subject

Example: subject1=-1, subject1=11

The numeral preceding = indicates the subject group; the numeral after = indicates the subject. If you would like to see results for the entire subject group, use (-) before the subject group number, i.e. subject1=-1

Also note that you can search by subject name using a keywords search.

Special Categories

Cost to Complete

Cost to Complete Range

Example: costToCompleteRange=0+TO+400

Please note that when costToCompleteRange is set, costToComplete is ignored

Resource

Grade Level

Resource Usage

Teacher Type

School Type

Challenge

Example: challengeId=18369

Please note that, in contrast to the challenge page (http://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.

Zone (State or sub-state regions)

To search by state code (e.g. TX) you can either do a keyword search or use the stateCode parameter (e.g. stateCode=NC).

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

You can sort your results by:

APPENDIX B: Facet Counts

An example of a JSON response with facet counts:

{
...
"proposals":[...],
"facetCounts":{
"location":{"zone":{"Illinois (State)":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":{"zone":{"AR":574, "AK":45, ..., "WY":68}}

If zone=311 in the search parameters:

"location":{
  "county":{"Baldwin":4,"Bibb":1,...,"Tuscaloosa":1},
  "district":{"Albertville City School Dist":23,"Auburn City School District":1,...,"Tuscumbia City School District":2}
  "city":{"Adamsville":1,"Albertville":23,"Wilmer":1 }
}

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), Resource Type (key: resourceUsage), 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.

APPENDIX C: Sample requests

Projects needing less than $200 to complete in classrooms with high level of poverty:
http://api.donorschoose.org/common/json_feed.html?costToCompleteRange=0+TO+200&highLevelPoverty=true &APIKey=DONORSCHOOSE

Southern California projects with an Arts & Music focus:
http://api.donorschoose.org/common/json_feed.html?zone=411&subject1=-1&APIKey=DONORSCHOOSE

Projects from Canoga Park:
http://api.donorschoose.org/common/json_feed.html? keywords=%22Canoga+Park%22&APIKey=DONORSCHOOSE

Topical / newsworthy projects:
http://api.donorschoose.org/common/json_feed.html?keywords=president&APIKey=DONORSCHOOSE
http://api.donorschoose.org/common/json_feed.html?keywords=climate+change&APIKey=DONORSCHOOSE

Partially funded projects belonging to Teach For America teachers
http://api.donorschoose.org/common/json_feed.html?partiallyFunded=true&teacherType=1&APIKey=DONORSCHOOSE

Projects from New York City charter schools
http://api.donorschoose.org/common/json_feed.html?zone=103&schoolType=1&APIKey=DONORSCHOOSE

Projects for technology resources for high school students
http://api.donorschoose.org/common/json_feed.html?proposalType=2&gradeType=4&APIKey=DONORSCHOOSE

How can I contact the DC.org tech team with any questions
about using the API?

We'd love to hear from you! Contact us at apiquestion (at) donorschoose (dot) org.