CapabilitiesCan 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. If you need audit-quality reporting for tracking account-critical events like affiliate commissions, you should register for our affiliate program and Commission Junction will provide industrial strength tracking, reporting, and billing. 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 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. 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. http://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. You can in query for multiple specific projects at once if you add the parameter "&solrQuery=(265145%20OR%20279655)" where 265145 and 279655 are project ID numbers. 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: http://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. Data detailsWhat 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. |
Frequently Asked Questions |