This guest post comes from Dr. Abir Qasem and Tanya Gupta. Qasem is an Assistant Professor of Computer Science, and Director of Academic Computing at Bridgewater College. Gupta works in corporate finance and risk management as senior resource management officer.
The New York Times API suite is most definitely among the top news APIs. It is well documented, has good testing tools, remains fairly stable, and has almost no surprises - all in all, a good example of a mature API suite. ProgrammableWeb lists 14 New York Times APIs. In this post we will help you get the most out of these technical offerings from the newspaper.
API Request Tool
If you don’t want to generate an API key or code, but just want to test a query, you can use the
API request tool to test the API. This console can be used as a query builder as well as a query tester. You can choose an API, use the check boxes to select a few parameters and the tool will build the query for you. You would then be able to view the resulting request and response on the right. This is a very useful tool for beginning programmers as this allows them to validate the query construction before they put it in their code. The API request tool allows you to quickly plow through all the APIs and select the ones that you want to dig into.
Our API Picks
While everyone will have their own favorite APIs, we thought the coolest APIs were probably the Campaign Finance API, the Movie Reviews API (we are both big movie buffs) and the Congress APIs. These are probably good mashup candidates too, if you use the NYT APIs for Campaign Finance or the Congress API with other relevant APIs such as the Sunlight Labs APIs.
Campaign Finance API
If you wanted to get the top 20 candidates by contribution total or debts owed, you would use the following:
where the category for Contribution Total is contribution-total and Debts Owed is debts-owed
Disbursements Total, End Cash,Individual Total, PAC Total, Receipts Total, and Refund Total are other categories you could use.
We find this API interesting as the data is substantial as it is compiled from other great sources, which include the following:
- The official Web site of the Office of the Clerk of the U.S. House of Representatives, for vote data
- The official Web site of the United States Senate, for vote data
- The Biographical Directory of the United States Congress, for member biographical information
- GovTrack.us, for member biographical information
- MIT Professor Charles Stewart's collection of Congressional data, for role information
- THOMAS (The Library of Congress), for bill data and nomination data
- The C-SPAN Congressional Chronicle, for floor appearances
- The Sunlight Labs Congress API, for Twitter and YouTube user names in member lists
Hilary Clinton’s Congress ID was C001041. The query to use for member vote positions is:
Here’s how it pops up on the API console/tool: http://prototype.nytimes.com/gst/apitool/index.html?api_id=4&request_id=...
and here’s a screen shot of the results or you can access it directly here
We started our NYT API use with the movie reviews API, not just because of the good documentation by the NYT folks, and overall ease of use, but also because of all the movie related data it has.
If you have a specific movie in mind, you can use a general query for pulling up the review:
http://api.nytimes.com/svc/movies/v2/reviews/search.xml?query=pulp+ficti... (you will need to include the API key for this one)
Here is a query for getting a list of recent reviews and NYT Critics pick, using the API Tool (screen shot below)
You can specify up to three search parameters , and in addition you can specify order, limit, offset, and response-format. If you specify more than three, an error will be returned.
You can limit by search keywords (movie title and indexed terms), NYT Critics' Picks, by Best 1,000 Movies by format, by a specific NYT critic, by publication-date and by opening date
The Good and Bad of New York Times APIs
Pros: New York Times deserves full credit for opening up their APIs (they are one of a very select group on newspapers that have done so). They also made an effort to engage the developer community through their forum.
Their efforts are already starting to pay off in the form of mashups that offer value to the NYT community and beyond. Among the smarter mashups out there that use the NYT APIs, one of the better ones is is instantwatcher.com which also uses Netflix, Rotten Tomatoes and other APIs.
Cons: All the same, NYT does have its fair share of detractors. Critics have complained that the NYT API use is hampered by their restrictions on commercial use and the fact that you can’t put the entire review but only include a snippet of the review. Others say that news APIs need to go beyond individual newspapers opening up their APIs to news aggregator APIs. An example is the Daylife API, which lets developers source, combine, and synthesize news and media content into applications. This interesting Hacker News discussion has both supporters and detractors of the NYT API.
All in all, here’s hoping that more newspaper and news sites follow the lead of NYT and open up their APIs. This will be just one way that news organizations can retain their value and respond effectively to the changing business model for newspapers by providing “short bites” and greater personalization, promote their content, and value-add to existing news-based products.