> For the complete documentation index, see [llms.txt](https://docs.os.uk/os-apis/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.os.uk/os-apis/core-concepts/getting-started-with-an-api-project.md).

# Getting started with an API project

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](https://osdatahub.os.uk/) 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.

{% hint style="success" %}

## 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](/os-apis/core-concepts/getting-started-with-an-api-project.md#regenerating-an-api-key) 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](https://osdatahub.os.uk/support/faqs/team-spaces). 
  {% endhint %}

## :new: 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

{% embed url="<https://www.youtube.com/watch?v=AocZYMHrIdY>" %}
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.
{% endembed %}

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

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

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><span data-gb-custom-inline data-tag="emoji" data-code="1f50d">🔍</span> <strong>Find out what OS APIs you have access to</strong></td><td><a href="/pages/pCLQSM1KYRrFmvpobExq#finding-out-what-os-apis-you-have-access-to">/pages/pCLQSM1KYRrFmvpobExq#finding-out-what-os-apis-you-have-access-to</a></td></tr><tr><td><span data-gb-custom-inline data-tag="emoji" data-code="2795">➕</span> <strong>Create a new API project and add an API to it</strong></td><td><a href="/pages/pCLQSM1KYRrFmvpobExq#creating-a-new-api-project-and-adding-apis-to-it">/pages/pCLQSM1KYRrFmvpobExq#creating-a-new-api-project-and-adding-apis-to-it</a></td></tr><tr><td><span data-gb-custom-inline data-tag="emoji" data-code="2795">➕</span> <strong>Add an API to an existing API project</strong></td><td><a href="/pages/pCLQSM1KYRrFmvpobExq#adding-an-api-to-an-existing-api-project">/pages/pCLQSM1KYRrFmvpobExq#adding-an-api-to-an-existing-api-project</a></td></tr><tr><td><span data-gb-custom-inline data-tag="emoji" data-code="1f50e">🔎</span> <strong>Find an API endpoint address</strong></td><td><a href="/pages/pCLQSM1KYRrFmvpobExq#whereisapiendpoint">/pages/pCLQSM1KYRrFmvpobExq#whereisapiendpoint</a></td></tr><tr><td><span data-gb-custom-inline data-tag="emoji" data-code="1fa84">🪄</span> <strong>Regenerate an API Key</strong></td><td><a href="/pages/pCLQSM1KYRrFmvpobExq#regenerating-an-api-key">/pages/pCLQSM1KYRrFmvpobExq#regenerating-an-api-key</a></td></tr><tr><td><span data-gb-custom-inline data-tag="emoji" data-code="2796">➖</span> <strong>Remove an API from a project</strong></td><td><a href="/pages/pCLQSM1KYRrFmvpobExq#removing-an-api-from-a-project">/pages/pCLQSM1KYRrFmvpobExq#removing-an-api-from-a-project</a></td></tr><tr><td><span data-gb-custom-inline data-tag="emoji" data-code="1f5d1">🗑️</span> <strong>Delete an API project</strong></td><td><a href="/pages/pCLQSM1KYRrFmvpobExq#deleting-an-api-project">/pages/pCLQSM1KYRrFmvpobExq#deleting-an-api-project</a></td></tr><tr><td><span data-gb-custom-inline data-tag="emoji" data-code="1f4c8">📈</span> <strong>Monitoring API usage</strong></td><td><a href="/pages/pCLQSM1KYRrFmvpobExq#monitoring-api-usage">/pages/pCLQSM1KYRrFmvpobExq#monitoring-api-usage</a></td></tr></tbody></table>

### :new: 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:

{% stepper %}
{% step %}

#### Log into your [OS Data Hub](https://osdatahub.os.uk/) account <a href="#log-into-your-os-data-hub-account" id="log-into-your-os-data-hub-account"></a>

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

<figure><img src="/files/GCwKMRa1F1C5GRR5kPn8" alt="Screenshot showing the OS Data Hub homepage." width="563"><figcaption><p>Screenshot showing the OS Data Hub homepage.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Navigate to the OS Data Hub workspace <a href="#navigate-to-the-os-data-hub-workspace" id="navigate-to-the-os-data-hub-workspace"></a>

Select *Data* from the menu bar to view your workspace.
{% endstep %}

{% step %}

#### Navigate to API Catalogue <a href="#navigate-to-the-os-selectbuild-recipe-library" id="navigate-to-the-os-selectbuild-recipe-library"></a>

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

<figure><img src="/files/b7I7VcKxEaeKNufGjt8W" alt="Screenshot of the API Catalogue screen in the OS Data Hub" width="563"><figcaption><p>Screenshot of the API Catalogue screen in the OS Data Hub.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### 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:

{% stepper %}
{% step %}

#### Log into your [OS Data Hub](https://osdatahub.os.uk/) account <a href="#log-into-your-os-data-hub-account" id="log-into-your-os-data-hub-account"></a>

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

<figure><img src="/files/GCwKMRa1F1C5GRR5kPn8" alt="Screenshot showing the OS Data Hub homepage." width="563"><figcaption><p>Screenshot showing the OS Data Hub homepage.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Navigate to the OS Data Hub workspace <a href="#navigate-to-the-os-data-hub-workspace" id="navigate-to-the-os-data-hub-workspace"></a>

Select *Data* from the menu bar to view your workspace.
{% endstep %}

{% step %}

#### Create a new API project <a href="#navigate-to-the-os-selectbuild-recipe-library" id="navigate-to-the-os-selectbuild-recipe-library"></a>

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

<figure><img src="/files/SBOkincdzTAy2U2eSTN0" alt="Screenshot of the API Projects screen in the OS Data Hub." width="563"><figcaption><p>Screenshot of the API Projects screen in the OS Data Hub.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Give your API project a name

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

<figure><img src="/files/ymocEcsNm6YtjyONX9In" alt="Screenshot of the API Projects screen in the OS Data Hub with the Give your new project a name dialog visible." width="563"><figcaption><p>Screenshot of the API Projects screen in the OS Data Hub with the Give your new project a name dialog visible.</p></figcaption></figure>
{% endstep %}

{% step %}

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

<figure><img src="/files/YW5PUAQ226gcop95o0kV" alt="The dedicated project page for your new API project – it will be empty at first until you add APIs to it." width="563"><figcaption><p>The dedicated project page for your new API project – it will be empty at first until you add APIs to it.</p></figcaption></figure>

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

<figure><img src="/files/xr4axiXDulU5dT7JskQj" alt="Screenshot of the Add API to this project dialog in the OS Data Hub." width="361"><figcaption><p>The <em>Add API to this project</em> dialog.</p></figcaption></figure>

*The API(s) will now appear in your project.*
{% endstep %}

{% step %}

#### View your API Key, secret and endpoint address/es

The *<*&#x50;roject Nam&#x65;*>* 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)

<figure><img src="/files/JqnJ6EUt91CjloNk5C8w" alt="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." width="563"><figcaption><p>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.</p></figcaption></figure>

*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.*
{% endstep %}
{% endstepper %}

### 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:

{% stepper %}
{% step %}

#### Log into your [OS Data Hub](https://osdatahub.os.uk/) account <a href="#log-into-your-os-data-hub-account" id="log-into-your-os-data-hub-account"></a>

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

<figure><img src="/files/GCwKMRa1F1C5GRR5kPn8" alt="Screenshot showing the OS Data Hub homepage." width="563"><figcaption><p>Screenshot showing the OS Data Hub homepage.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Navigate to the OS Data Hub workspace <a href="#navigate-to-the-os-data-hub-workspace" id="navigate-to-the-os-data-hub-workspace"></a>

Select *Data* from the menu bar to view your workspace.
{% endstep %}

{% step %}

#### Find the existing API project you want to add an API to <a href="#navigate-to-the-os-selectbuild-recipe-library" id="navigate-to-the-os-selectbuild-recipe-library"></a>

Select *APIs* > *API Projects,* then click the *\<project name>* link in the list of projects to open the dedicated project page.
{% endstep %}

{% step %}

#### Add a new API to the existing API project

* Click *+ Add API*.&#x20;

<figure><img src="/files/mt6HFQx2nRAvHX9gDXDf" alt="Example API project showing the Actions and + Add API buttons" width="347"><figcaption><p>The <em>Actions</em> and <em>+ Add API</em> buttons.</p></figcaption></figure>

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

<figure><img src="/files/xr4axiXDulU5dT7JskQj" alt="Screenshot of the Add API to this project dialog in the OS Data Hub." width="361"><figcaption><p>The <em>Add API to this project</em> dialog.</p></figcaption></figure>

*The API will be added to your project and you'll be able to use the same project API Key.*
{% endstep %}
{% endstepper %}

### Finding an API endpoint address <a href="#whereisapiendpoint" id="whereisapiendpoint"></a>

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

{% stepper %}
{% step %}

#### Log into your [OS Data Hub](https://osdatahub.os.uk/) account

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

<figure><img src="/files/GCwKMRa1F1C5GRR5kPn8" alt="Screenshot showing the OS Data Hub homepage." width="563"><figcaption><p>Screenshot showing the OS Data Hub homepage.</p></figcaption></figure>

{% endstep %}

{% step %}

#### Navigate to the OS Data Hub workspace

Select *Data* from the menu bar to view your workspace.
{% endstep %}

{% step %}

#### 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.
{% endstep %}

{% step %}

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

<figure><img src="/files/JqnJ6EUt91CjloNk5C8w" alt="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." width="563"><figcaption><p>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.</p></figcaption></figure>

*You will also find the API Key and secret for the project on the dedicated project page.*
{% endstep %}
{% endstepper %}

### Regenerating an API Key

{% hint style="info" %}

## 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.
  {% endhint %}

To regenerate an API Key for one of your projects:

{% stepper %}
{% step %}

#### Log into your [OS Data Hub](https://osdatahub.os.uk/) account <a href="#log-into-your-os-data-hub-account" id="log-into-your-os-data-hub-account"></a>

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

<figure><img src="/files/GCwKMRa1F1C5GRR5kPn8" alt="Screenshot showing the OS Data Hub homepage." width="563"><figcaption><p>Screenshot showing the OS Data Hub homepage.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Navigate to the OS Data Hub workspace <a href="#navigate-to-the-os-data-hub-workspace" id="navigate-to-the-os-data-hub-workspace"></a>

Select *Data* from the menu bar to view your workspace.
{% endstep %}

{% step %}

#### Find the API project you want to regenerate the API Key for <a href="#navigate-to-the-os-selectbuild-recipe-library" id="navigate-to-the-os-selectbuild-recipe-library"></a>

Select *APIs* > *API Projects,* then click the *\<project name>* link in the list of projects to open the dedicated project page.
{% endstep %}

{% step %}

#### Regenerate the API Key for the project

* Click *Actions > Regenerate API Key*.

<figure><img src="/files/qs1ttFU3LSme3LIOzWaR" alt="Example API Dashboard showing Actions > Regenerate API Key button"><figcaption></figcaption></figure>

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

<figure><img src="/files/RRcj6rpXcyCxGfqdngW9" alt="Example API Dashboard showing Regenerate API Key? confirmation dialog"><figcaption></figcaption></figure>

*The API Key and API secret will automatically change for your project.*
{% endstep %}
{% endstepper %}

### Removing an API from a project

To remove an API from a project:

{% stepper %}
{% step %}

#### Log into your [OS Data Hub](https://osdatahub.os.uk/) account <a href="#log-into-your-os-data-hub-account" id="log-into-your-os-data-hub-account"></a>

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

<figure><img src="/files/GCwKMRa1F1C5GRR5kPn8" alt="Screenshot showing the OS Data Hub homepage." width="563"><figcaption><p>Screenshot showing the OS Data Hub homepage.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Navigate to the OS Data Hub workspace <a href="#navigate-to-the-os-data-hub-workspace" id="navigate-to-the-os-data-hub-workspace"></a>

Select *Data* from the menu bar to view your workspace.
{% endstep %}

{% step %}

#### Find the API project you want to remove an API from <a href="#navigate-to-the-os-selectbuild-recipe-library" id="navigate-to-the-os-selectbuild-recipe-library"></a>

Select *APIs* > *API Projects,* then click the *\<project name>* link in the list of projects to open the dedicated project page.
{% endstep %}

{% step %}

#### Remove an API from the project

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

<figure><img src="/files/LIFcSgJ4VA0wvikXZvHJ" alt="Example API Dashboard showing Remove from project button for OS NGD API - Tiles"><figcaption></figcaption></figure>

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

<figure><img src="/files/wr1qZmsmu31Pbl0hJTUn" alt="Example API Dashboard showing Remove OS NGD API - Tiles from this project confirmation dialog"><figcaption><p>The Remove &#x3C;API name> from project dialog.</p></figcaption></figure>

*The API will automatically be removed from your project.*
{% endstep %}
{% endstepper %}

### Deleting an API project

To delete one of your API projects:

{% stepper %}
{% step %}

#### Log into your [OS Data Hub](https://osdatahub.os.uk/) account

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

<figure><img src="/files/GCwKMRa1F1C5GRR5kPn8" alt="Screenshot showing the OS Data Hub homepage." width="563"><figcaption><p>Screenshot showing the OS Data Hub homepage.</p></figcaption></figure>

{% endstep %}

{% step %}

#### Navigate to the OS Data Hub workspace

Select *Data* from the menu bar to view your workspace.
{% endstep %}

{% step %}

#### 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.
{% endstep %}

{% step %}

#### Delete the API project

* Click *Actions > Delete this project*.

<figure><img src="/files/0YxorLyEMq8M616D9Iwf" alt="Example API Dashboard showing Actions > Delete this project button"><figcaption><p>Example API Dashboard showing Actions > Delete this project button</p></figcaption></figure>

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

<figure><img src="/files/5JWXfbNeJ42gj7kb0Oon" alt="Example API Dashboard showing the Permanently delete this project and its API key? confirmation dialog"><figcaption><p>Example API Dashboard showing the Permanently delete this project and its API key? confirmation dialog.</p></figcaption></figure>

*The project will be deleted from your API Dashboard.*
{% endstep %}
{% endstepper %}

### :new: Monitoring API usage

To monitor API usage:

{% stepper %}
{% step %}

#### Log into your [OS Data Hub](https://osdatahub.os.uk/) account

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

<figure><img src="/files/GCwKMRa1F1C5GRR5kPn8" alt="Screenshot showing the OS Data Hub homepage." width="563"><figcaption><p>Screenshot showing the OS Data Hub homepage.</p></figcaption></figure>
{% endstep %}

{% step %}

#### Navigate to the OS Data Hub workspace

Select *Data* from the menu bar to view your workspace.
{% endstep %}

{% step %}

#### 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*](https://www.ordnancesurvey.co.uk/customers/public-sector/public-sector-geospatial-agreement)*. OS OpenData Plan users will just see their OpenData usage.*

<figure><img src="/files/TPzawWNVTVmDDPcXog1a" alt="Screenshot of the API Dashboard page in the OS Data Hub showing total API usage for your organisation over the last month." width="563"><figcaption><p>API Dashboard page showing <em>total API usage for your organisation over the last month.</em></p></figcaption></figure>
{% endstep %}

{% step %}

#### View your API transaction history

Select *APIs* > *API Transaction History*.

<figure><img src="/files/4OaaVal1ukQAWlBQNU8N" alt="Screenshot of the API Transaction History page on the OS Data Hub showing total API usage for specific APIs over time and by project." width="563"><figcaption><p>API Transaction History page showing <em>total API usage for specific APIs over time and by project.</em></p></figcaption></figure>

*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).*
{% endstep %}
{% endstepper %}

{% hint style="info" %}

## 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](https://osdatahub.os.uk/support/faqs/plans#apiTransactions).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.os.uk/os-apis/core-concepts/getting-started-with-an-api-project.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.