More than 2 years after James originally published (w)here are those APIs you promised?, it's time to set the record straight on APIs for GOV.UK.
This post is a technical post about APIs - a way of accessing structured data on a website in ways other than with a web browser. Read about APIs on the Service Design Manual.
What happened to those APIs?
In short, we haven't built them because of other, more important, things that needed our focus (see continuous planning on the Service Manual). APIs have dropped off the GOV.UK business plan for 2015, due to the transition of more than 300 agencies onto GOV.UK. Our priorities have shifted towards fulfilling the original vision for GDS - one domain (for government), and we're excited about the possibilities this will open up. This means we can't commit to supported and documented APIs for GOV.UK content in this financial year.
Will there ever be supported APIs?
Yes! Once we have the transition complete we'll be refocusing our efforts on the platform itself - this will include looking at additional user needs like structured government data. We're also rebuilding parts of GOV.UK around APIs, which will emerge publicly when they're ready - the APIs listed below are all used internally, but because we control both the client and server implementations we aren't calling them publicly supported.
What is there to use?
Despite reprioritisation, we do have several external APIs right now, and I'm going to outline these below in case they're useful. When exploring these, it's important to remember that these are unsupported APIs - we reserve the right to change, destroy, or otherwise break these with no notice. If that's still okay for your needs, please read on.
Business finance support API
This is the only supported API on this list. We've blogged about it before.
Update: as part of our migration work to make our frontend architecture simpler, we will be removing the business support API. See Tim's blog post for more details and dates you need to know.
The warning message will give more details of how to continue getting content about business finance support.
We’ll link to more details on the removal of this API once we’ve published them.
Content API
This API provides what we used to refer to as 'mainstream' content. It's not comprehensive (this is one of the main reasons that we don't support this API), eg anything that lives under https://www.gov.uk/government/ (about 95% of our content) isn't covered by this API. Available at https://www.gov.uk/api/GOVUK-URL-HERE.json, eg https://www.gov.uk/api/bank-holidays.json. Additionally, even for things that are considered 'mainstream', if the page has been manually overriden (like DVLA's 'check vehicle tax' start page), what you see on GOV.UK won't match up with what the JSON response contains. This is powered by the govuk_content_api. Example output.
Tags API
Tags are the concept behind the 'mainstream' navigation on GOV.UK. This API allows one to list content tagged with a section, eg in https://www.gov.uk/browse/education, education is the tag. Available at https://www.gov.uk/api/with_tag.json?section=working. Secondary tags are available as URL encoded query params, eg https://www.gov.uk/api/with_tag.json?section=education%2Fschool-life. Example output.
Government organisations API
This API provides a list of all the organisations on GOV.UK, including their sub-and-parent-organisations. Traversing this API (results are linked) should give one an idea of the structure of government. Available at https://www.gov.uk/api/organisations, or to see an individual organisation: https://www.gov.uk/api/organisations/cabinet-office. Example output.
Worldwide locations API
This API provides a list of 'world locations' (not all of the results are countries, hence 'locations') as provided by the Foreign and Commonwealth Office. This data is used internally by the worldwide index page on GOV.UK, which brings together all published dealings with overseas locations. Available at https://www.gov.uk/api/world-locations (list is paginated), and traversable down to country level. Example output.
Worldwide organisations API
A child of the world locations API, this API allows one to see all the official foreign offices attached to a particular location, eg all embassies in Afghanistan. Available at https://www.gov.uk/api/world-locations/LOCATION-SLUG/organisations, eg https://www.gov.uk/api/world-locations/afghanistan/organisations. Example output.
Search API
This is currently an Elasticsearch backed search, served and with additional indexing and analysis added by our rummager application. This is the same API that currently drives our unified search feature. Available at https://www.gov.uk/api/search.json?q=government+digital+service. Example output.
Finally...
When planning for the next phase of APIs mentioned above, we'd like to take user needs into consideration - so please consider the APIs linked here as some ideas and sketches of what we could do, and give us feedback on what else you'd like to see. I've made a GitHub Gist of all the example JSON linked from this post.
7 comments
Comment by Jennifer Bruce posted on
Please explain what API stands for/means at least once. (I had understood that there were to be fewer acronyms and unexplained terminology on GOV.UK and associated pages.) I had to google API just to be absolutely certain that this wasn't of relevance to me - and that it wasn't worth forwarding to IT colleagues for whom we sometimes monitor developments.
Comment by Brad Wright posted on
Jennifer,
You're absolutely right, will update the post!
Comment by Jennifer Bruce posted on
Thanks Brad
Comment by Geoff Stockham posted on
As someone who has used many of the above APIs (and sometimes been bitten by breaking changes!), I would recommend watching the GitHub repositories to keep up-to-date on what's changed, what's available and to act as documentation.
Comment by Bob Smith posted on
It's a great shame that you've scotched your founding Service Design Manual principles and taken the attitude of "just get the website out of the door". Crow-barring in an API afterwards is terrible software practice. Just read those old blog posts, which held so much promise, and then reread the excuses.
Comment by Anna Rose posted on
It's a shame the roll out has been delayed but it will be great when you get there. Nice to see some joined up thinking being rolled out too, which is of course complicated to set up but for all our benefit in the end. So they delay to the APIs is necessary.
Comment by Andrew posted on
We have been looking at the API information you have here. Is it possible to get an api for a page such as this? https://www.gov.uk/funding-rules-2015-to-2016-introduction-and-purpose#introduction
We can get info for https://www.gov.uk/api/organisations/skills-funding-agency but would like to be able to drill down further.