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


---

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

```
GET https://docs.distance.tools/tools/api/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.