Helping your users co-create the value they need

How easy is it for all types of developers and agencies to find government APIs?

Last updated: 25 August 2020

Who should read this: Digital government team leaders, government API teams, users of government APIs

What it’s about: Government API discoverability is the process of making sure all developers can easily find and understand what APIs are published and maintained by a government, in an accessible, equitable, and user-friendly manner. A new research project is being carried out to document current and best practices for Government API discoverability.

Why it’s important: Understanding and sharing best practices will help governments publish their APIs to allow others to discover, access and use them in ways that create value and drive digital economies. This research needs the input of digital government and government API teams, as well as from developers wanting to use government APIs in their work.

Special note: The views expressed in this article represent the project researchers from Platformable. This research is partly funded by the European Commission, ISA2 programme, Innovative Public Services action, within the API4IPS project, in collaboration with the Joint Research Centre, the Directorate-General for Informatics, and the Directorate‑General for Communications Networks, Content and Technology.

Taking a user-centred design approach, a government API provider needs to start by thinking from the developer’s perspective. So, imagine you are a developer working at a business productivity startup. Your company wants to build a new app targeting first responders, to help them connect with local businesses and coordinate access to essential supplies during extreme weather events and other local environmental crises. You want to find out what APIs are available that you could connect into your app (and use according to the terms of use and following attribution requirements, where necessary): things like being able to verify the user’s identity, share latest news feeds on extreme weather, link to databases of local businesses using certain keywords, and other functionalities. Where do you find out what is available?

Where do you find out what government APIs are available?

You could:

  • Use a search engine like DuckDuckGo or Google and enter a combination of keywords like “first responder”, “your area (city, region, nation)”, “business registration”, “extreme weather alerts”, and so on
  • You could look on the relevant government’s website, but where? You could scan:
    • Their open data portal?
    • Emergency services department?
    • Weather department?
    • Business support or economic development?
    • Government communications team?
  • The problem with this approach is that it requires you, as the developer, to understand and be able to navigate through government departments to find each agency that might be the custodian of a relevant API for your app, or through government catalogues that have large numbers of open data APIs available.

  • Or you could go to the government’s API developer portal if they have one.
Infographic shows a developer trying bto enter keywords in DuckDuckGo search engine, looking up a government's website by departmental area, and going to a Government's API developer portal
Current discoverability workflow for a developer looking for Government APIs

That’s the current scenario for most developers looking to use government APIs in their apps.

Ideally, a developer should be able to:

  • Find available, relevant government APIs quickly
  • Be able to start learning what functionalities they offer and how they can be integrated into their apps, and
  • Be able to find APIs they can use as a business to transact and connect with government (for example, to register their business activities, pay taxes, book venues or parking, apply for rebates or funding, etc).

Perhaps the developer has gone to the government’s developer portal which has a catalogue of all available APIs. Perhaps they find out what APIs are available because a government digital ecosystem facilitator has reached out to invite them to a network meeting for digital creators in their industry. Perhaps the government has hosted a hackathon or information session or meetup. Perhaps the developer read about the government’s APIs in the tech or local business media.

All of these methods of finding out about a government’s APIs are called "discoverability strategies".

Government API discoverability is the process of making sure all developers can easily find and understand what APIs are published and maintained by a government, in an accessible, equitable, and user-friendly manner.

But now imagine a future scenario. As a developer, you assume the government has a developer portal. You scroll down the home page of the government website and in the footer menu, you find the link that says “Developers” just like you are used to doing when you go to any other large agency website, like for a bank or fintech, or for a telco, or tech company.

The link takes you to a developer portal which includes a catalogue of all the government APIs, but that is now over 100 APIs for the one government. So instead, you use the portal search wizard. With this, you enter your business registration number, or if you don’t want to share that, you describe a little about your business: how many people work there, some keywords that describe the type of work you do. Then you are given two lists:

Gov APIs as 'raw ingredients' Gov APIs as transactional services
A list of data and service APIs that match your keywords and that could be useful to help you build products. These APIs were useful to other businesses with similar keywords (like a recommendation engine) or business category (from your registration details). These APIs also match keywords from the API metadata that was entered by the government API creators. A list of data and service APIs that match your keywords and that could be useful to help you build products. These APIs were useful to other businesses with similar keywords (like a recommendation engine) or business category (from your registration details). These APIs also match keywords from the API metadata that was entered by the government API creators.
Infographic showing ideal workflow for a developer looking for government APIs: they go to the government developer portal site via the main government webpage, enter a few details about their business needs and receive a list of APIs that match their business needs ands a list of APIs that can help them transact directly with government
Potential ideal workflow to assist developers find the government APIs they need 

Wouldn’t that be neat? It is possible in the future, but first governments need to focus on the basic building blocks for API discoverability before building these more interactive features.

Underlying assumptions about digital government and APIs

But there are also some underlying assumptions in government API discoverability. Discoverability assumes:

  • The government has decided it wants to take a platform approach in which third parties can build new products and services using government services and data exposed via API. (To learn more about why API teams need to understand their government’s platform vision, check out Proposal 2 in the API Framework for Digital Governments.)
  • The government is facilitating domain-level (that is, industry or sector-based) ecosystems (like transport, environment, healthcare, safety, or so on) and has identified key user groups that might each want to integrate government APIs for specific use cases (see Proposal 6, 7 and 11 of the API Framework for Digital Governments which focus on how governments can build ecosystems and take a product management approach to involving stakeholders and targeted developer segments.)

As digital government processes transform how governments operate, they are increasingly investing in APIs as the composable units to link systems and expose functionalities and data to their ecosystems. But this is still a fairly new phenomena, so API and digital government leaders often need to show that they are creating value for citizens, the economy, and the environment by making APIs available. Often that value is measured in terms of how many apps or developers use the government APIs, and what products they have built.

Discoverability is a key mechanism that can help governments achieve their intended goals with their APIs. That is:

Discoverability can make sure that government APIs are accessible and available to a wider audience of potential users. These users can then build more products and services, thus demonstrating the value of the government APIs.

A Government API Discoverability Taxonomy

We have identified and categorised 20 discoverability strategies that governments can use to encourage developers to find their APIs:

20 Government API discoverability strategies organised into 4 categories:  API design: 1. Metadata 2. Standardization. Category 2 API publication: 3. Developer Portals 4. Search Engine Optimization (SEO) 5. Directory Listings 6. APIs on Open Data Platforms 7. Business-focused portals 8. GitHub accounts 9. Postman collections Category 3: Ecosystem facilitation: 10. Social media 11. Hackathons and Challenges 12. Developer Summits and Information sessions 13. Accelerators 14. Case studies, storytelling 15. Domain-level ecosystem networks and websites 16. Mailing lists Category 4: Automated tooling: 17. Citizen and no-code tools 18. Service discovery tools 19. Predictive analytics 20. Recommendation engines
20 Government API discoverability strategies organised into 4 categories

Participate in our research study

We are currently conducting research to discover:

  • Are there other strategies governments are using for discoverability?
  • Which of these discoverability strategies are governments using the most, what are the best practices, and which are the most cost-effective?
  • What discoverability strategies ensure that government APIs are equitable, accessible and available to all potential users?
  • How are governments identifying key user groups for their APIs and measuring whether their discoverability strategies are effective for these user groups?
  • What templates, checklists, and other tools would help governments increase discoverability of their APIs?

Our research will be conducted over the next few months and we would love to have your involvement. This research is partly funded by the European Commission, ISA2 programme, Innovative Public Services action, within the API4IPS project, in collaboration with the Joint Research Centre, the Directorate-General for Informatics, and the Directorate‑General for Communications Networks, Content and Technology.

To participate in our study as either a government API or digital government leader, or as a developer or agency that would like to make more use of government APIs, you can: