APIs for all

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.


  1. Paul Downey

    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 ;^)

    Link to this comment
    • James Stewart

      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.

      Link to this comment
      • Robbie Clutton (@robb1e)

        +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.

        Link to this comment
  2. Wayne Austin

    Yeah not keen on using /api in the URL either. Looking forward to the full API ref's and docs

    Link to this comment
  3. akismet-91c9ccbc322b791411b23b013a20d94e

    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

    Link to this comment
    • Vivek

      Has there been any movement on Formal API specifications?

      Link to this comment
  4. davidfsmith

    +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.

    Link to this comment
  5. frankieroberto

    +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 to make the search results discoverable by web browsers and API clients.

    Link to this comment
  6. Steph Gray

    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?

    Link to this comment
    • James Stewart

      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.

      Link to this comment
  7. Bob

    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 😉

    Link to this comment
  8. Hot Miami DJ

    Government digital service is a great decision of all country in the world. I really appreciate to this post. thanks.

    Link to this comment
  9. Anthony Williams (@abitgone)

    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:

    Great work guys. Can't wait to see what's coming next.

    Link to this comment
    • James Stewart

      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.

      Link to this comment
  10. James Gawn

    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.).

    Link to this comment
  11. 2012年11月07日(水)の日常 - okaz::だめにっき

    [...] APIs for all | Government Digital Service [...]

    Link to this comment
  12. Hussain Shafiei

    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 or will I have to try to find it all from various sources? Any help would be appreciated.

    Link to this comment
  13. Peter Sheldon

    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)

    Link to this comment
  14. Andy Piper

    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 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?

    Link to this comment
    • James Stewart

      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.

      Link to this comment
  15. Jon

    Hi James,

    I was using the RSS feeds on however they have now disappeared, is there somwehere I can access these?

    Thanks! Jon

    Link to this comment
  16. Tim Joyce

    Do you have some example javascript for accessing the travel advice please? I can download for example afghanistan.json and access it with:

    But using:

    Returns nothing.

    Many thanks.

    Link to this comment
    • Tim Joyce

      I have spent a bit more time on this and realised that I should have been using JSONP.

      However when I use:
      I get the error:
      Message: Expected ';'
      Line: 1
      Char: 18
      Code: 0

      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

      Link to this comment
      • James Stewart

        Hi Tim,

        The JSON's valid (I just checked it with 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.


        Link to this comment
  17. Ian Heritage (@kerednai)

    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?

    Link to this comment
    • James Stewart

      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

      Link to this comment
  18. Przemyslaw Hass

    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, provides invalid JSON.

    '' provide only one link about PIP.

    I had to use (unpublished) version of that query:
    I discovered that when tried: - it redirected me to the (note, will not work).

    However still doesn't work.

    'Content with tag': like doesn’t work too, though 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

    Link to this comment
    • James Stewart

      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 that'll make sure your request goes to the right place and we'll get back to you asap.


      Link to this comment
      • Przemyslaw Hass

        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

        Link to this comment
  19. Georgios

    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.

    Link to this comment
  20. Rob

    Can you explain why the information on the page is different from the data you get when looking at the JSON feed from


    Link to this comment
    • James Stewart

      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.


      Link to this comment
  21. Rob

    Can you tell me how the “detailed_guide” type pages work on the site?


    json feed is

    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?

    Link to this comment
  22. Rob

    That last example appears to be broken now 🙁

    Try this instead..


    Link to this comment
    • Brad Wright

      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.


      Link to this comment
  23. Simon Neaves


    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.


    Link to this comment
  24. Suren

    What are the implications of this supreme court ruling an use of API ?? (

    Link to this comment
    • Carrie Barclay

      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.

      Link to this comment