🔃Getting started with an API project

Learn how to create new API projects in the OS Data Hub; find your API Key, secret & endpoint address(es); regenerate an API Key; delete an API project; remove APIs from projects, & monitor API usage.

To access any of the OS APIs, you need an API Key and / or an API secret token. These credentials are scoped to a dedicated API project that is linked to your OS Data Hub account. You can find your API projects and project API Keys in the API Projects page in the OS Data Hub, where you can fully manage all aspects of your OS APIs.

Tips for API best practice

• We recommend that you set up different API projects so you can monitor usage more easily.

• You can regenerate an API Key if needed (for example, if you mistakenly shared it with someone who shouldn't have access to the API data); see the Regenerating an API Key section for instructions on how to do this.

• The dedicated project page for each API project shows the APIs in that project, their endpoint addresses, and the API Key and API secret for the project.

• You can use Team Spaces to manage who in your organisation has access to a project; learn more on the OS Data Hub portal.

🆕 Step-by-step video guide for getting started with API projects

The following short video runs you through how to:

• Find out what OS APIs you have access to

• Create a new API project and add APIs to it

• Find an API Key, API secret and API endpoint address

• Regenerate an API Key

• Remove an API from a project

• Delete an API project

• Monitor API usage

Short YouTube video with instructions on how to find out what OS APIs you have access to; create a new API project; find an API Key, API secret and API endpoint address; regenerate an API Key; remove an API from a project; delete an API project, and monitor API usage.

Step-by-step listed instructions for getting started with API projects

The following step-by step listed instructions will run you through how to:

🔍 Find out what OS APIs you have access to

➕ Create a new API project and add an API to it

➕ Add an API to an existing API project

🔎 Find an API endpoint address

🪄 Regenerate an API Key

➖ Remove an API from a project

🗑️ Delete an API project

📈 Monitoring API usage

🆕 Finding out what OS APIs you have access to

To find out what OS APIs you / your organisation has access to under your current plan:

1

Log into your OS Data Hub account

Click Log in on the OS Data Hub menu bar to log into your account.

Screenshot showing the OS Data Hub homepage.

2

Navigate to the OS Data Hub workspace

Select Data from the menu bar to view your workspace.

3

Navigate to API Catalogue

Choose APIs > API Catalogue from the secondary navigation menu.

Here, you'll find a list of all the APIs you / your organisation has access to under your current plan.

Screenshot of the API Catalogue screen in the OS Data Hub.

Creating a new API project and adding APIs to it

Before you can access the OS APIs, you need to add at least one API to a new or existing project in the OS Data Hub and generate an API Key.

To create a new API project, add an API (or multiple APIs) to it and generate an API Key:

1

Log into your OS Data Hub account

Click Log in on the OS Data Hub menu bar to log into your account.

Screenshot showing the OS Data Hub homepage.

2

Navigate to the OS Data Hub workspace

Select Data from the menu bar to view your workspace.

3

Create a new API project

Select APIs > API Projects, then click the Create a new project button.

Screenshot of the API Projects screen in the OS Data Hub.

4

Give your API project a name

Enter an API project name in the dialog, then click Create project.

Screenshot of the API Projects screen in the OS Data Hub with the Give your new project a name dialog visible.

5

Add an API or multiple APIs to your new API project

• In the dedicated project page that appears, click the + Add an API to this project button.

The dedicated project page for your new API project – it will be empty at first until you add APIs to it.

• In the Add API to this project dialog, find the API you want to add from the list (either scroll down the list of available APIs or enter the API name in the search bar), then click the Add to project button. (You can add multiple new APIs to the project in this dialog if you wish.)

• Click Done to close the dialog.

The Add API to this project dialog.

The API(s) will now appear in your project.

6

View your API Key, secret and endpoint address/es

The <Project Name> page opens and displays:

• The project API Key (for example, _GCk3L4TFnuKwcwG1PMJBtOyuipu6MOlV)

• The project API secret (for example, _zi7Vbor5f8i2ZTMs)

• A list of the APIs in your project

• Other API-specific information (for example, the API endpoint address for each API in your project)

The dedicated project page for your new API project, showing the APIs in your project, their endpoint addresses, the API Key for the project and the API secret for the project.

You can return to this page at any point in the future by opening API Projects in the secondary navigation menu, then clicking on the name of the project. This is handy if you need to copy your Project API Key or API endpoint address/es, or if you need to regenerate your API Key.

Adding an API to an existing API project

Before you can access the OS APIs, you need to add at least one API to a new or existing project in the OS Data Hub and generate an API Key.

To add a new API to an existing API project:

1

Log into your OS Data Hub account

Click Log in on the OS Data Hub menu bar to log into your account.

Screenshot showing the OS Data Hub homepage.

2

Navigate to the OS Data Hub workspace

Select Data from the menu bar to view your workspace.

3

Find the existing API project you want to add an API to

Select APIs > API Projects, then click the <project name> link in the list of projects to open the dedicated project page.

4

Add a new API to the existing API project

• Click + Add API.

The Actions and + Add API buttons.

• In the Add API to this project dialog, find the API you want to add from the list (either scroll down the list of available APIs or enter the API name in the search bar), then click Add to project. (You can add multiple new APIs to the project in this dialog if you wish.)

• Click Done to close the dialog.

The Add API to this project dialog.

The API will be added to your project and you'll be able to use the same project API Key.

Finding an API endpoint address

To find the API endpoint address for an API in one of your API projects:

1

Log into your OS Data Hub account

Click Log in on the OS Data Hub menu bar to log into your account.

Screenshot showing the OS Data Hub homepage.

2

Navigate to the OS Data Hub workspace

Select Data from the menu bar to view your workspace.

3

Find the API project that contains the API you want to know the endpoint address of

Select APIs > API Projects, then click the <project name> link in the list of projects to open the dedicated project page.

4

Look up the API endpoint address

The API endpoint address(es) will be displayed in this dedicated project page. If a project uses multiple OS APIs, then each one will have its own API endpoint address.

The dedicated project page for an API project, showing the APIs in your project, their endpoint addresses, the API Key for the project and the API secret for the project.

You will also find the API Key and secret for the project on the dedicated project page.

Regenerating an API Key

Notes on regenerating an API Key

• You might want to regenerate an API Key for a project if you've mistakenly shared the key with someone who shouldn't have access to the API data or if someone still has access to a project but they've left your organisation.

• Regenerating an API Key for a project creates a new API Key for the project and makes the old key unusable.

• After regenerating an API Key for a project, you'll need to update any applications or connected software to use the new key in order for them to continue working.

• You'll still be able to see historical usage statistics for the project from before you regenerated API Key.

To regenerate an API Key for one of your projects:

1

Log into your OS Data Hub account

Click Log in on the OS Data Hub menu bar to log into your account.

Screenshot showing the OS Data Hub homepage.

2

Navigate to the OS Data Hub workspace

Select Data from the menu bar to view your workspace.

3

Find the API project you want to regenerate the API Key for

Select APIs > API Projects, then click the <project name> link in the list of projects to open the dedicated project page.

4

Regenerate the API Key for the project

• Click Actions > Regenerate API Key.

• Enter the one-time code to confirm your action, then click Regenerate API Key.

The API Key and API secret will automatically change for your project.

Removing an API from a project

To remove an API from a project:

1

Log into your OS Data Hub account

Click Log in on the OS Data Hub menu bar to log into your account.

Screenshot showing the OS Data Hub homepage.

2

Navigate to the OS Data Hub workspace

Select Data from the menu bar to view your workspace.

3

Find the API project you want to remove an API from

Select APIs > API Projects, then click the <project name> link in the list of projects to open the dedicated project page.

4

Remove an API from the project

• Click the Remove from project button for the specific API you wish to remove.

• In the Remove <API name> from project dialog that appears, click the Remove API from project button to confirm the removal.

The Remove <API name> from project dialog.

The API will automatically be removed from your project.

Deleting an API project

To delete one of your API projects:

1

Log into your OS Data Hub account

Click Log in on the OS Data Hub menu bar to log into your account.

Screenshot showing the OS Data Hub homepage.

2

Navigate to the OS Data Hub workspace

Select Data from the menu bar to view your workspace.

3

Find the API project you want to delete

Select APIs > API Projects, then click the <project name> link in the list of projects to open the dedicated project page.

4

Delete the API project

• Click Actions > Delete this project.

Example API Dashboard showing Actions > Delete this project button

• Enter the one-time code to confirm your action, then click Permanently remove project.

Example API Dashboard showing the Permanently delete this project and its API key? confirmation dialog.

The project will be deleted from your API Dashboard.

🆕 Monitoring API usage

To monitor API usage:

1

Log into your OS Data Hub account

Click Log in on the OS Data Hub menu bar to log into your account.

Screenshot showing the OS Data Hub homepage.

2

Navigate to the OS Data Hub workspace

Select Data from the menu bar to view your workspace.

3

View your API Dashboard

Select APIs > API Dashboard.

Here you will be able to see the total API usage for your organisation over the last month, split into usage for OS OpenData and OS Premium data – the latter will show as Public Sector data if you are a Public Sector Geospatial Agreement (PSGA) Member. OS OpenData Plan users will just see their OpenData usage.

API Dashboard page showing total API usage for your organisation over the last month.

4

View your API transaction history

Select APIs > API Transaction History.

API Transaction History page showing total API usage for specific APIs over time and by project.

Here you will be able to dig into usage for specific APIs over time and by project. You can filter by API project, API name, and time (week, month or year).

What's an API transaction?

API transactions are how we measure and charge for the use of our APIs. What counts as one API transaction depends on the data format. Raster and vector transactions are measured in map views. Others are measured as feature requests.

For more information and a table outlining transaction rates for each OS API, please see the 'What's an API transaction?' FAQ on the OS Data Hub.