Changing the trends API

Thursday, 25 August 2011

We’re looking to make some changes to our trends API very soon, and wanted to run our planned changes past you before we did. There are a number of different methods for trends, some of which return the same data in the same format, others which return the same data in a slightly different format. So, it’s time for a little spring cleaning, albeit in the fall.

What we want to do is deprecate the redundant API calls soon and standardize on a common URL format. Right now, the endpoints GET trends and GET /1/trends/trending.json (an older endpoint, no longer documented) are actually the same API request, just with two URLs. There is also GET trends/current, a slightly newer format of the same data, but also a duplicate of GET trends/:woeid.

The endpoint we would like everyone to move to is GET trends/:woeid, instead of using any of the other three API requests mentioned above.

This particular method leverages woeid (Yahoo! Where On Earth ID) to specify the location of the trending information that you want returned. So if you wanted to get global trending information returned in JSON format, you would specify /1/trends/1.json (in this case, :woeid = 1 == world). By using the GET trends/:woeid URL request you can easily change which part of the world you receive trends for. Combining this method with the trend_location data returned by GET account/settings allows you to localized trends to each user of your service. The list of :woeids we support can be queried through GET trends/available.

As well as standardizing the trends URL we are also planning to switch the trends API to JSON only. The reason for this is because the use of XML on the trends API is significantly low and removing support would allow us to free up resources for other developments.

Our suggested timeline for this is 4 weeks, meaning the older trends endpoints and XML format would no longer function after September 25, 2011. While one month’s time is our plan, we’d like to know how much time you need to make these changes. Please give us your feedback here.