Frequently Asked Questions

Request a key

Right now API Keys are only available to DonorsChoose partners with commitments of over $100K. If you're interested in discussing a partnership, you can reach out to our team and request an API key here.

Please include your best estimate of the daily and peak number of requests your app will make against the API for our capacity planning purposes.

Transactional features

If you need to use the transactional features, mention that in your email. Also give us some indication of how your app will use our transactions and your best estimate of the daily and peak number of transactions.

Yes! See the "Completed" section of JSON Requests for details on how to query for completed projects.

Our API automatically appends Google Analytics tracking codes, with your API key embedded, to all the referral URLs. So we can isolate the web traffic you send us and provide one-off reporting on it, including such metrics as: visits, donations, avg donation size, etc.

If you'd like this information, reach out to us and let us know your API key. At this time, we do not have any automated traffic/analytics reports you can access on your own.

In some scenarios, we can enable you to make project donations via the API. For example, you could show your site visitors classroom classroom project listings and then process the donation to a project behind-the-scenes without having to route your site visitor to DonorsChoose's front-end!

However, we're unable to make this option available to everyone. So if you're interested in using API project donations, get in touch with us so we can discuss how best to meet your needs.

If you want to dig into the technical details first, you can learn more about transactions.

Yes! Learn more about Transactions.

Our projects are now geo-tagged: we can provide a project's lat/long coordinates in our JSON responses!

We have also enabled these types of geo-spatial queries: "bounding box," "center + distance," and "projects near me." And we added a new concise JSON response format that's useful for returning lots of points at once.

See the appropriate sections of our JSON request and JSON response documentation for details on how to employ the new geo functionality.

Yes! We've had a number of partners do this and it's a great way to tastefully showcase the impact of your API usage.

First, create a Giving Page. Then determine the Giving Page's unique identifier, which you can see as the "id" parameter in the Giving Page's public URL, eg. https://www.donorschoose.org/donors/viewChallenge.html?id=25298 is Giving Page number 25298.

If you then append the parameter "&partnerID=xyzxyz" to all your API calls?where xyzxyz is your Giving Page's number?then we'll be able to associate any immediately resulting donations to your Giving Page. (You'll see that adding that parameter prompts the API to append &challengeid=xyzxyz to every DC.org project URL you get back.)

However, this form of tracking/reporting is unfortunately not super robust in that our system will lose track of the referral if the user leaves the specific project page on which they landed at DonorsChoose, browses around the site, and gives to a different project. So it should not be relied upon for audit-quality reporting.

You can sort project listings to get your results in order of soonest-to-expire. However, there is currently no way to further filter project listings by expiration date.

You can pull up to 50 projects. Simply change the 'projects per page' count to 50, located at the bottom of the search page, and use the new url for your feed.

We've included only a few project attributes in the feed, in order to keep it concise. There is currently no way to formulate a request that adds more per-project meta-data in the feed.

Yes! For example, the Durant Tuuri Mott Elementary School in Flint, Michigan has the NCES ID 261452005099.

So a JSON request of this form will bring back all the projects at that school: https://api.donorschoose.org/common/json_feed.html?APIKey=[YOUR_API_KEY]&ncesId=261452005099

A word of warning that we do not have NCES ID numbers for every single school in our database.

Yes, our friend Tom authored these great notes. Thanks, Tom!

Yes, although you'll likely need to implement some form of JSONP in order to avoid getting an error due to the same-origin security policy. As detailed in our API Specific Parameters section, we do support using a callback function for this purpose.

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.

Our API supports both http and https requests. https is recommended when possible. For example, both of these URLs will work:

http://api.donorschoose.org/common/json_feed.html?APIKey=[YOUR_API_KEY]&subject6=-6&matchingId=-1

https://api.donorschoose.org/common/json_feed.html?APIKey=[YOUR_API_KEY]&subject6=-6&matchingId=-1

Every project on DonorsChoose has a unique ID that never changes, even after the project is completed. It will always be an integer.

Since we license this data, we are unfortunately not permitted to distribute it freely.

If you have a special need for it, get in touch with us and we'll try our best to help.

You can query for completed projects using the "&historical=true" API parameter as documented.

However, projects are not accessible via the API for a short period after their funding is complete while we're waiting for the teacher to confirm they still need the materials. This usually happens <24 hrs, but can take up to 3-4 days.

Our API doesn't currently provide this data, sorry!

At present, we don't have the actual front-end messages available via the API.

Our front-end creates these messages at display-time by calculating the delta between the value in the expirationDate field and now.

If you want to do the same calculation, know that projects actually expire at 12:01AM Eastern of the day after the expiration date, not on the day of.

All search parameters currently available are listed here.

Banners, Logos and Media materials