Update: we've blogged more recently about the current state of APIs on GOV.UK.
Last week I talked about GOV.UK's APIs and how we use them to build and monitor the site. Now it's time to say a little more about what they mean for other developers who might want to use our content and data.
As with everything we do at GDS, our approach to APIs is driven by user need. Our core focus with APIs has been to approach them as a tool to help serve the vast majority of user needs that we're serving with web pages. But we know there are many opportunities to serve needs by working with other people to provide the right APIs.
The same APIs that GOV.UK uses internally are available to anyone using the site. For most of our content-rich pages you can get the full content of the page and some supporting information (such as which categories it lives in and whether it's designed for businesses) with a simple change of URL. So for:
You'd use:
As on the beta, we've included links in the page headers pointing to the API version. A similar approach works for getting search results.
There are still quite a few rough edges in these APIs (eg. a little inconsistency in some results and that annoying .json on the end of the URLs above). We've been so highly focussed on getting the main site ready that there's not been time to add the extra polish we'd like. Over the next couple of months we'll be making time to remove a few inconsistencies and pull together some documentation and an explorer to help developers find their way around.
What we really need now is feedback to help us understand the needs of those partners who might build things with our APIs. If you've got ideas or questions please do get in touch and help us shape the next iteration of GOV.UK APIs.
50 comments
Comment by Suren posted on
What are the implications of this supreme court ruling an use of API ?? (http://flip.it/TZhJd)
Comment by Carrie Barclay posted on
Hi Suren, thanks for your comment. We don't think this will have any effect on our work, but we'll be monitoring legal developments closely.
Comment by Simon Neaves posted on
Hi,
Apologies for coming in quite cold and if this is not the appropriate place to ask this, but do the APIs confirm to a set of schemas? How can we know up front what attributes are required/optional, and if the end points conform to a set of 'types' e.g. index/article etc.
Thanks
Comment by James Stewart posted on
Simon - the APIs are very much still in development. Our latest update is at https://insidegovuk.blog.gov.uk/2014/09/15/current-state-of-apis-on-gov-uk/
Comment by Rob posted on
That last example appears to be broken now 🙁
Try this instead..
https://www.gov.uk/classifying-rice
and
https://www.gov.uk/api/classifying-rice.json
Comment by Brad Wright posted on
Hi Rob,
At the moment the APIs are still in flux - they're not officially supported so I wouldn't expect the URLs to remain stable.
While we work on what it is we actually want to do we won't be able to provide support for external parties using them programmatically, so I'm afraid we won't be able to help you at the moment.
We're hoping to revisit this work when we complete the transition of the remaining government agencies onto GOV.UK - that's our focus for the moment.
Brad
Comment by Rob posted on
Can you tell me how the “detailed_guide” type pages work on the gov.uk site?
e.g.
https://www.gov.uk/regional-trade-agreements-with-chile-mexico-south-africa-europe-gulf-states-mediterranean-mercosur-and-the-caribbean
json feed is
https://www.gov.uk/api/regional-trade-agreements-with-chile-mexico-south-africa-europe-gulf-states-mediterranean-mercosur-and-the-caribbean.json
But the json feed contains hardly any of the information which is displayed on the user-facing page.
How can I retrieve this information programmatically?
Comment by Rob posted on
Can you explain why the information on the page https://www.gov.uk/tax-disc is different from the data you get when looking at the JSON feed from https://www.gov.uk/api/tax-disc.json
Thanks!
Comment by James Stewart posted on
Hi Rob,
I believe you're already in touch with one of my colleagues through our support channels about the details of this? We're trialling a new format for the tax disc page and that's not fully exposed via the API at the moment. Once the trial is completed we'd aim to bring everything back in sync.
James.
Comment by Georgios posted on
It's good practice to keep the "api" directory reference esp if the URL mirrors a sites URL plus it's good practice to keep the json exstention to allow a developer using the API to see what script to expect but most importantly it allows the sites developers to add other scripts for more compatibility across other languages.
Comment by Przemyslaw Hass posted on
Hi James.
I am trying to understand the API and I really love how simple it is. The “lang” field made me very happy, because I am translating GOV’s publications into different language. This simple field allows me to use the same API for both languages. No need to write two separate applications. The API explains itself, and it’s easy to “copy” your database’s structure and translate the data very quickly.
I found the “/api/” prefix easy to handle, just use kind of StringReplace function that exists in every programming language, so I can’t complain about that. Personally, I think its good idea.
Can't think about any 'more convenient' way to access the API that will be really more convenient.
To compare if my translated content is up-to-date, I use the field 'updated_at' so I don't have to compare all of the data, and that's 'like' for your API.
There are other nice things like ‘other relevant content’, sections and tags… Unfortunately it is there, where my problem with the API starts.
For example, https://www.gov.uk/api/with_tag.json?section=benefits%2Fchild provides invalid JSON.
'https://www.gov.uk/api/with_tag.json?section=benefits' provide only one link about PIP.
I had to use (unpublished) version of that query:
https://www.gov.uk/api/tags.json?type=section&parent_id=benefits
I discovered that when tried:
https://www.gov.uk/browse/xyz.json - it redirected me to the https://www.gov.uk/api/tags.json?type=section&parent_id=xyz (note, https://www.gov.uk/api/browse/xyz.json will not work).
However https://www.gov.uk/api/tags.json?type=section&parent_id=benefits%2Fchild still doesn't work.
'Content with tag': like https://www.gov.uk/api/tags/sections/benefits%2Fchild.json doesn’t work too, though https://www.gov.uk/api/tags/sections/benefits.json do.
Since you use the tags and sections on GOV’s website, I understand it is working somehow – I assume you use the same API for GOV. I am wonder, how to extract those things without manual handling. It holds my project in the alpha (covered with dust on my localhost), because I dislike the idea of handwriting tags and sections.
Would be nice to have access to tags, sections and other things directly, providing as parameter numeric id or '+' separated words (not benefits%2Fchild but benefits+child).
I am sorry if my post looks somehow chaotic, just wanted to share as much, as I can in short and simple way.
Kind Regards
P. Hass
Comment by James Stewart posted on
Hi Przemyslaw,
I'm sorry to hear you're having trouble with the JSON you're getting from several pages. The JSON I get when I use the URLs you listed is valid so we clearly need to do a bit more investigation to see why you're getting different results.
These comments aren't really the best place for detailed discussions of this sort. If you could complete our support form https://www.gov.uk/feedback/contact that'll make sure your request goes to the right place and we'll get back to you asap.
James.
Comment by Przemyslaw Hass posted on
Thank you James for quick answer.
Of course, I'll use the 'contact' form. I have revised all my scripts to check for possible errors on my site to avoid commenting things that doesn't work because of my fault.
By the way, do you plan to allow access (through the API) to tools like Benefits Advisor? I guess yes, and can't wait for that.
I see that your team works hard, and would like to say I really appreciate that. All of you can be proud of job well done. Can only guess how much work you had and still have. The longer I browse GOV.UK, the more I am impressed, not only by the API but the whole content you provide in one place.
Best Regards
P. Hass
Comment by Ian Heritage (@kerednai) posted on
It would be nice if you updated the example in your original document to remove the /api/ in the URL rather than requiring users to read through the comments to find out this is now unnecessary. Any plans to create a developer portal?
Comment by James Stewart posted on
Hi Ian,
The URLs with /api/ are still the better way to access the JSON versions of content. That's under review but for now it's just that the other URLs are designed to redirect to the /api/ equivalent.
We're doing a bit of work at the moment to get a better understanding of who the users are for our APIs and how we can best provide support. I'd love to hear more about how you're using the API and what you'd be looking for from a developer portal if we were to launch one. Comments here are great or you can reach me at james.stewart@digital.cabinet-office.gov.uk
Comment by Tim Joyce posted on
Do you have some example javascript for accessing the travel advice please? I can download for example afghanistan.json and access it with:
$.getJSON("afghanistan.json",function(result){
alert(result);
But using:
$.getJSON("https://www.gov.uk/api/foreign-travel-advice/afghanistan.json",function(result){
alert(result);
Returns nothing.
Many thanks.
Comment by Tim Joyce posted on
I have spent a bit more time on this and realised that I should have been using JSONP.
However when I use:
$.getJSON("https://www.gov.uk/api/foreign-travel-advice/afghanistan.json?jsoncallback=?",{})
I get the error:
Message: Expected ';'
Line: 1
Char: 18
Code: 0
URI: https://www.gov.uk/api/foreign-travel-advice/afghanistan.json?jsoncallback=jQuery19105645641892865305_1368006944041&_=1368006944042
This seems to happen for any country page.
Could anyone tell me if I am doing somethign wrong, or is there a problem with the JSON syntax?
Many thanks
Comment by James Stewart posted on
Hi Tim,
The JSON's valid (I just checked it with jsonlint.com). I'd suspect you're actually getting a 403 Forbidden HTTP response? We've not done any work yet to make the API work well for JSONP and it may well conflict with some of our security policies.
That's something we'll be revisiting over the next few months, but in the meantime you're probably best off setting up a proxy on your server so you can make the API requests server-side and then use regular ajax requests to connect back to your own server. That approach will also give you more control of your caching so is often preferable anyway.
James.
Comment by Jon posted on
Hi James,
I was using the RSS feeds on http://www.fco.gov.uk/content/en/rss-outbound/travel-advice/travel-advice-summary1.rss? however they have now disappeared, is there somwehere I can access these?
Thanks! Jon
Comment by James Stewart posted on
Hi Jon,
It looks like those URLs slipped through the net and didn't get redirected. Thanks for lettting us know.
The team are working on this so they should redirect to the new feed URLs very soon now. For the time being you can find feed URLs from https://www.gov.uk/foreign-travel-advice
Comment by Andy Wrigley posted on
Hi James,
I was using the FCO's XML Country index, now using https://www.gov.uk/api/foreign-travel-advice.json much easier. Thanks for the link.
Just one query:
will there be a maximum of one image element for an individual country like https://www.gov.uk/api/foreign-travel-advice/afghanistan.json ? I hope so, but if not it would useful to have an "{image caption "and "{image parts_slug" to identify to which part of the content each image relates.
Comment by Roo Reynolds posted on
Thanks Andy. Glad you're liking the new .json API for foreign travel advice.
There _should_ reliably be a maximum of one image per country. (We'll definitely consider further improvements to the API if that situations ever looks likely to change though).
Comment by Andy Piper posted on
So the passport-fees example you give currently results in a 403 and dropping /api/ results in it being directed back to the +/api/ URL and the same 403.
Would be nice to have some API docs rather than just a link from the gov.uk FAQ to here, and then an example that doesn't currently work 🙁 any idea when those kind of lists of information for developers will be made available?
Comment by James Stewart posted on
We're aware of the 403 issue and working to fix it. Sorry it caught you. You can usually get around it by adding a query string (any query string) to the request - does that work?
We're also planning to get the API better documented, provide an explorer, and so on later in the year. It's really important to us to do that, but not as high a priority as the ongoing migration of departments onto GOV.UK so we've had to hold off for a while.
Comment by Peter Sheldon posted on
Is there any plan for a search widget to be made, similar to that which was offered on the DirectGov site? (See my earlier posting)
Comment by Hussain Shafiei posted on
Is there an API that lets you know all elected positions on a national and local levels in the UK. i.e. All councils, (Parish, local, district, GLA), MP, Scottish, and Welsh assembly's? I want to know if this is kept by GOV.uk or will I have to try to find it all from various sources? Any help would be appreciated.
Comment by James Stewart posted on
That's not information we currently have and is generally outside the remit of GOV.UK which is focussed on government rather than parliament. You might find the data you're looking at via MySociety's tools such as http://www.writetothem.com
Comment by Hussain Shafiei posted on
My Thanks James will try to se if they can help us out.
Comment by 2012年11月07日（水）の日常 - okaz::だめにっき posted on
[...] APIs for all | Government Digital Service [...]
Comment by James Gawn posted on
Great post. A smallish addition that I'd like to see is an API that provides a complete listing of all the content URIs (answers etc.).
Comment by James Stewart posted on
Thanks James. We do have a sitemap at https://www.gov.uk/sitemap.xml which may give some of what you want?
Comment by James Gawn posted on
Ah, that's exactly what I was looking for. Thanks.
Comment by Anthony Williams (@abitgone) posted on
Firstly, thanks for all the work you have already done – we're already using things like the bank holiday calendars in our back-end to automate things that we've previously had to do by hand.
We'd find it hugely useful if the JSON API endpoints for the following pages returned the actual data on the page, not just the HTML content of the page wrapped in JSON:
https://www.gov.uk/vehicle-tax-rate-tables
https://www.gov.uk/vat-rates
Great work guys. Can't wait to see what's coming next.
Comment by James Stewart posted on
Already responded to this on twitter, but for completeness...
We're definitely hoping to make that kind of data more accessible but it's not been a top priority for the launch of GOV.UK. Hopefully we'll get there soon!
Please do keep sending feedback like this - it's really helpful as we work out where to focus as we try to make the API more useful.
Comment by Hot Miami DJ posted on
Government digital service is a great decision of all country in the world. I really appreciate to this post. thanks.
Comment by Bob posted on
Looks like you did manage to remove "/api" from the path already, but that's now a 403 -- while the non-"/api".json URL does work. A redirect would have been nice 😉
Comment by Bob posted on
Hmm.. and now, seconds later, both URLs work. Though the two URLs give different results.
Never mind!
Comment by James Stewart posted on
Hmmmm... the non /api URLs shouldn't be working yet! Can you email govuk-feedback@digital.cabinet-office.gov.uk with the links you're trying?
When we do make that change we'll make sure we don't just switch /api off - it'll be either a redirect or (more likely) we'll just let both work.
Comment by Steph Gray posted on
Sounds great. Do you have a Guardian-style micro-apps model planned for the future, to help roll smaller third party apps/APIs into services delivered with the scalability of GOV.UK behind it?
Comment by James Stewart posted on
That'd definitely be an option, but we've not got any specific plans at the moment. There's a lot more work and thinking to do as we look at the next stages of GOV.UK and other government services.
Comment by frankieroberto posted on
+1 for removal of /api from the URL, and for optional use of content-negotiation (as well as the .format extension).
Might be a nice idea to add an OpenSearch description resource (see http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document) to make the search results discoverable by web browsers and API clients.
Comment by James Stewart posted on
It's on its way! https://www.gov.uk/search/opensearch.xml
Comment by Peter Sheldon posted on
Is there any plan for a search widget to be made, similar to that on DirectGov site?
The DirectGov site offered a simple search widget which allowed a user enter a location and to select from a number of categories such as "Jobs" or "Bin collections". When run, the user was taken to an appropriate page on the DirectGov site.
An example of the DirectGov search widget may be seen in the left hand menu of
http://www.hertsdirect.org/your-community/
Comment by davidfsmith posted on
+1 for API removal, I also like the .json extension for the same reasons as already mentioned. It should certainly generate some interesting re-uses of the data and content you hold. Further as a web developer myself it also helps me to sell in the concept of API's to my clients as well, maybe they won't need them now (although useful for single page style web apps) but certainly useful later and saves time spent re-engineering. GDS's approach helps make a lot of things easier for selling into clients (as I see it) Great work.
Comment by akismet-91c9ccbc322b791411b23b013a20d94e posted on
Not keen on /api in the URI, looking forward to the docs I think I have a few cool ideas to make a few apps
Comment by Vivek posted on
Has there been any movement on Formal API specifications?
Comment by Wayne Austin posted on
Yeah not keen on using /api in the URL either. Looking forward to the full API ref's and docs
Comment by Paul Downey posted on
Great stuff James, and should lead to some interesting mashups, especially when combined with much of GOV.UK's content being published under the liberal Open Government Licence.
Of course with URIs, there is no consensus on style, which is actually fine as none is needed for The Web to work, but I actually like the .json suffix because it's useful when testing in a browser and I'm not so keen on the word "/api/" in the path of the URL, but you already know that ;^)
Comment by James Stewart posted on
Good points, Paul.
The /api/ prefix is an unfortunate reflection of our internal architecture. I hope we can make it (and .json vs. an Accept header) optional in a future release.
Comment by Robbie Clutton (@robb1e) posted on
+1 for removal of "/api/" being in the path.
As well as the Accept header and implied extension, I've also seen X- headers such as X-PJAX used successfully to imply how the client would like content back.