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 PHP, Java, Actionscript, C#, Ruby, Python, Objective C, and many others.

Learn more about JSON and access popular packages/parsers at http://www.json.org/.

How can I make an HTTP request?

Our API is simple: you make an HTTP request--assembled very similarly to a regular DonorsChoose.org front-end project search--and receive classroom project listings in a JSON response.

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.

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

How can I receive a unique API key?

Feel free to use the default API key "DONORSCHOOSE" for evaluative or testing purposes, or non-production-quality prototypes.

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, request a unique API key from us.

Also, we suggest you join our email list so we can notify you of any functional or policy changes.

How can I use a website (RSS) feed to be notified of projects that match my interests?

At DonorsChoose.org, you can setup a website (RSS) feed to notify you of proposals that match your interests. Note that you must use a feed reader in order to subscribe to website feeds.

To setup a feed, first navigate to any DonorsChoose.org proposal search results page by keyword searching or browsing, or advanced searching.

Then scroll to the bottom of the page to access the feed for those search results.

Initially your feed reader will show the same proposals as the search results page from which you setup the feed.

Thereafter, your feed reader should only show proposals as they "debut" onto the first page of search results for the search criteria you've specified.