> For the complete documentation index, see [llms.txt](https://docs.distance.tools/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.distance.tools/tools/api/api-reference.md).

# API Reference

## Authentication

Follow the [getting-started guide](/tools/api/getting-started.md) how to setup your [developer account](/tools/api/getting-started.md) and get your API credentials.

### **Headers**

| Name              | Value            |
| ----------------- | ---------------- |
| `X-Billing-Token` | `<your API key>` |

## OpenAPI definition

{% embed url="<https://raw.githubusercontent.com/StephanGeorg/distance.tools-public-docs/main/api/openapi.yaml>" %}

## Status codes

| Code                                       | Description                                                                                            |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| <mark style="color:green;">**200**</mark>  | Valid request and all locations or waypoints could be geocoded.                                        |
| <mark style="color:orange;">**400**</mark> | Invalid request with information about validation.                                                     |
| <mark style="color:orange;">**404**</mark> | Valid request but not all locations or waypoints could be geocoded.                                    |
| <mark style="color:orange;">**429**</mark> | Load balancer rejected the request because too many request in parallel or your usage limits exceeded. |

## Units <a href="#units" id="units"></a>

All distances are given in **kilometers**. To convert distances into miles, they must be multiplied by 0.621371. Maritime distances are also given in **nautical miles**.

The travel duration for car routing is given in **seconds.** For maritime routes, which are given in **hours** `duration` is calculated with a speed of 20 knots. 20 knots = 20 NM / hour.