# OS NGD API – Features

## What is OS NGD API – Features?

OS NGD API – Features gives you simple access to the OS National Geographic Database (OS NGD)

OS NGD API – Features allows you to

* Request specific feature types and their attributes using spatial or attribute queries.
* Interrogate highly detailed feature information.​​
* Freely discover what data collection are available.​​
* Explore the data schemas.​​
* Request data in GeoJSON format.​​
* Visualise Ordnance Survey data and apply your own styling.​

The API uses the same naming convention as OS NGD to allow you to explore themes and collections easily.

The [technical specification](https://docs.os.uk/osngd/getting-started/access-the-os-ngd-api/os-ngd-api-features/technical-specification) on the OS Data Hub goes into detail about the different themes that are accessible.​

​The API is compliant with OGC API standards.​

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-cd3645df7b74bd1432cc3662f9d661ac2d246564%2Fngd-features-api-collections.jpg?alt=media" alt="Table showing the NGD Themes and the features types in each of them" width="483"><figcaption><p>OS NGD Collections</p></figcaption></figure>

## How do I access the API?

Get access to the API through the OS Data Hub. The getting started guide can be accessed [here](https://docs.os.uk/osngd/getting-started/access-the-os-ngd-api/os-ngd-api-features/getting-started).​

* Your API key can be found in the API Dashboard by clicking ‘Add to Project’ under the OS NGD API – Features section​​

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-8cbce750e03a4b80448e188c29ddfb83516b5ebb%2Fngd-features-api-access-1.png?alt=media" alt="screenshot form the OS DataHub highlighting the Add to API project button"><figcaption></figcaption></figure>

You will now be able to find the API EndPoint address with your API key under your projects

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-96afe55cb9597169be85951f89b65e819e069ab2%2Fngd-features-api-access-2.png?alt=media" alt="screenshot form the OS DataHub highlighting the API endpoint that is created with your key"><figcaption></figcaption></figure>

With your API key you can access the API through GIS Software (such as QGIS and Cadcorp) and through programming languages such as Python and R. ​

The [getting started guide](https://docs.os.uk/osngd/getting-started/access-the-os-ngd-api/os-ngd-api-features/getting-started/gis-software/qgis) has a walk through on getting the API in QGIS.

Example scripts for getting started with the API can be found online:​

* R script for calling the API and outputting a Shiny web app [here](https://github.com/OrdnanceSurvey/osngd-resources/blob/main/jupyter-notebooks/r/shiny/os-ngd-api-features.ipynb)​
* Code examples for on OS Labs [here](https://labs.os.uk/public/osngd/os-ngd-api-features/)​

## What are the main benefits of the API?

* Plug and play – easily set up in QGIS to explore NGD data
* More flexible – pull in exactly the data you want
* No ordering or waiting – less time processing and storing data
* Easy Testing – great for quick and easy analysis of features

The table below shows the attributes that are available to query against on top of the options available in OS Select+Build.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-05a722cca8548bb381371d22a5eab22a1dac8b73%2Fos-features-api-attributes.png?alt=media" alt="Image of a table showing the attributes that are available to query against on top of the options available in OS Select+Build"><figcaption></figcaption></figure>

## How is the OS Features API different to the OS NGD API – Features?

The main difference between the new OS NGD API – Features and the OS Features API is the OS NGD API – Features is for accessing OS NGD data.

OS NGD attribution can be explored through the OS NGD layers found in the OS NGD API – Features API

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-4a503bf642b954016085cd88fea65c5032acae68%2Fngd-features-api-difference.png?alt=media" alt="Image of a map with a feature highlighted and a table of attribution"><figcaption></figcaption></figure>

## Limitations

There are a number of considerations to keep in mind when using the API.

* Limits – the API can return 100 features in a single call. Most GIS software will keep calling the API to bring in the requested features so it is important to set a feature limit when setting up the API. Pagination will be required when using a scripting language, this is explained in the next side.
* Scale – the API is not designed to create a scalable map of Great Britain across zoom levels. It is designed to interrogate specific features and small areas. ​
* Access – the API does not have the ability to access OS NGD Address Theme, the Administrative & Statistical Theme data or Water Catchments​.

<figure><img src="https://3774974716-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzIfdYInJITdcxaLLMhlD%2Fuploads%2Fgit-blob-c80bb720fe9e3bdd315007ae4c8cfa0c2afab974%2Fos-features-api-limits.png?alt=media" alt="Image of a dialogue box from QGIS showing the settings to allow 100 features at a time"><figcaption></figcaption></figure>

## Pagination

The API returns 100 features per page and the JSON response will include the URL for the following page

Most GIS already understand how to page as its part of the OGC standard. So remember to set limits to avoid calling back the entire country.

However, when using a scripting language you will need to page through the results by utilising the offset attribute.