Frequently Asked Questions - Data for Education
15113
page-template-default,page,page-id-15113,page-child,parent-pageid-15119,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

Frequently Asked Questions

Where’s the API key?

You don’t need a key to get started!

Our trial key provides full access to all our API functionality, it’s “DONORSCHOOSE” and you’ll see it used throughout our documentation. Once your app is up and humming, you should proceed to…

Request a key

Email apikey (at) donorschoose {dot} org.

Include your best estimate of the daily and peak number of requests your app will make against the API for our capacity planning purposes. If you can give us some indication of how your app will use our API, we’d love to hear about it! We will very likely quickly approve your API key request and we’ll only contact you directly if something comes up down the line.

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.

Can I query for completed projects?

Yes!

Serving up completed projects can be especially fun since they’re usually accompanied by great thank-you photos and there are many more completed projects (>130,000 at this writing) than live projects (ranges 14,000-20,000 over the school year).

See the “Completed” section of JSON Requests for details on how to query for completed projects.

Can I get reporting/analytics information on the traffic that my API usage is referring to DonorsChoose.org?

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.

Can I take donations on my own site and register the transaction with DonorsChoose.org behind-the-scenes?

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.org’s front-end!

However, we’re unable to make this option available to everyone. So if you’re interested in using API project donationsget 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.

Can I generate DonorsChoose.org gift cards using the API?

Yes!

Learn more about Transactions.

Can I get a geo-code/lat-long value for projects via the API? Can I do a geo-spatial query for projects, eg. ‘bounding box’ or ‘point plus distance’?

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.

Can you create a publicly visible page where folks can see the projects supported via my API integration?

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.org, browses around the site, and gives to a different project. So it should not be relied upon for audit-quality reporting.

Can I filter project listings by expiration date?

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.

Can I pull more than 10 projects using the RSS Feed?

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.

Is it possible to pull more project attributes via RSS than what’s listed?

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.

Is it true there are some unsupported API hacks that might be useful?

Yes, there are some things you can do via our API that aren’t intentionally enabled by the interface. Usually this entails passing commands directly through to our SOLR search engine.

For example…

You can exclude all projects of a specific teacher type if you add the parameter “&solrQuery=(NOT%20teachertypes:X)” where X is the teacherType ID, eg. “1” to your API call.

Can you query for projects by their school’s NCES ID?

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=DONORSCHOOSE&ncesId=261452005099

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

Do you have any tips for using the API with PHP and AJAX?

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

Can I integrate classroom project listings into my app on the client-side?

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.

How can I make JSON and other asset requests via SSL / HTTPS?

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=DONORSCHOOSE&subject6=-6&matchingId=-1

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

What type of identifiers are DonorsChoose.org’s unique project IDs?

Every project on DonorsChoose.org has a unique ID that never changes, even after the project is completed.

It will always be an integer, typically with 6 digits. There will never be fewer than 5 or greater than 7 digits.

Where does the shortDescription field come from?

The shortDescription is usually authored by DonorsChoose.org volunteers–usually other teachers who are very experienced using our site–who review and approve the projects before posting. The shortDescription is used across the site wherever we’re not showing the entire essay, eg. search results, Giving Pages.

The volunteers prefer to use the teachers’ own words so the shortDescription is often copy-pasted excerpts from the full essay (known in our API as the “synopsis”). However, it should be treated as a unique piece of content since it cannot be programmatically extracted from the essay.

Can you provide a mapping of every state, city, county, and school district’s unique DonorsChoose.org identifier?

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.

Do projects show up in the completed results as soon as they are fully funded?

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.

How do I get the ‘2 hours ago’ time-stamp for completed projects, like I’m seeing in the front-end UX?

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

How do I get the ‘6 hours left’ or ‘3 days left’ count-down time-stamps for soon-to-expire live projects, like I’m seeing in the front-end UX?

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.

Many city names are truncated after 13 characters. Is it possible to get the full city name?

Unfortunately these abbreviations are sourced into our system directly from our school data provider. As such, we don’t have the full city names and can’t provide them.

Our school data provider is MDR, a Dun & Bradstreet subsidiary, that in turn gets the school data from NCES, a government agency

Where can I find a map of search parameters?

All search parameters currently available are listed here.

How to contact you?

Search our discussion group

Search our public discussion group for developers and data crunchers
Your question may already have been asked and answered!

Ask our discussion group

Ask your question in our discussion group
You’ll have to join our discussion group to do so, but that takes just a few moments. Our preference is to answer your question in the discussion group in order to benefit other folks who might have similar question. Another benefit of asking there is that a fellow developer who has worked with our API in the past and knows it well might beat us to the punch with an even better answer to your question!

Get in touch with us directly

If you have a question that’s not appropriate for that public forum, you can get in touch with us directly.

Non-technical question

If it is a non-technical question, use our Contact form and a member of our team will be happy to answer your questions.

Technical question

If it is a technical question, email our engineering team at apiquestion (at) donorschoose {dot} org.

Where do I get banners, logos, one pagers, etc?