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. From Monday 20 March 2017 the API will show a warning and the content it returns will no longer be updated. From Tuesday 18 April 2017, the API will stop returning content and will only display a warning. The API will be completely removed on Tuesday 2 May 2017.
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.
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/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 are the concept behind the 'mainstream' navigation on GOV.UK. This API allows one to list content tagged with a section, eg in
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/afghanistan/organisations. Example output.
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.
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.