# Geo Distance API
> Great-circle (as-the-crow-flies) navigation maths between latitude/longitude points. The distance endpoint returns the straight-line distance in metres, kilometres, miles and nautical miles, plus the initial and final compass bearing and the nearest 16-point compass direction. The destination endpoint computes where you end up from a start point, a bearing and a distance, and the midpoint endpoint finds the great-circle midpoint between two points. Perfect for proximity and radius search, geofencing, flight and shipping estimates, "distance from me" features and mapping. Pure local computation — no key, no third-party service, instant. These are straight-line distances on a spherical earth, not road routes. Live, nothing stored. 4 endpoints. Distinct from road routing, GeoJSON geometry measurement and coordinate-format conversion.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/geodistance-api/..."
```

## Pricing
- **Free** (Free) — 1,045 calls/Mo, 2 req/s
- **Starter** ($1/Mo) — 8,850 calls/Mo, 8 req/s
- **Pro** ($21/Mo) — 139,500 calls/Mo, 20 req/s
- **Mega** ($59/Mo) — 735,000 calls/Mo, 50 req/s

## Endpoints

### Geo

#### `GET /v1/destination` — Destination from start + bearing

**Parameters:**
- `lat` (query, required, string) — Start latitude Example: `51.5074`
- `lng` (query, required, string) — Start longitude Example: `-0.1278`
- `bearing` (query, required, string) — Bearing in degrees Example: `148`
- `distance` (query, required, string) — Distance Example: `343.5`
- `unit` (query, optional, string) — m|km|mi|nm (default km) Example: `km`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/geodistance-api/v1/destination?lat=51.5074&lng=-0.1278&bearing=148&distance=343.5&unit=km"
```

**Response:**
```json
{
    "data": {
        "lat": 48.860159,
        "lng": 2.360012,
        "unit": "km",
        "bearing": 148,
        "distance": 343.5
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:45.010Z",
        "request_id": "3a8b5d56-60f7-44ae-9ce4-377439047b4e"
    },
    "status": "ok",
    "message": "Destination point",
    "success": true
}
```

#### `GET /v1/distance` — Distance + bearing between points

**Parameters:**
- `lat1` (query, required, string) — Start latitude Example: `51.5074`
- `lng1` (query, required, string) — Start longitude Example: `-0.1278`
- `lat2` (query, required, string) — End latitude Example: `48.8566`
- `lng2` (query, required, string) — End longitude Example: `2.3522`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/geodistance-api/v1/distance?lat1=51.5074&lng1=-0.1278&lat2=48.8566&lng2=2.3522"
```

**Response:**
```json
{
    "data": {
        "miles": 213.476134,
        "meters": 343556.535,
        "compass": "SSE",
        "kilometers": 343.556535,
        "final_bearing": 150.0211,
        "nautical_miles": 185.505688,
        "initial_bearing": 148.1156
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:45.113Z",
        "request_id": "926aa176-4c42-4444-b0b2-a2b83c945d1f"
    },
    "status": "ok",
    "message": "Distance + bearing",
    "success": true
}
```

#### `GET /v1/midpoint` — Midpoint between two points

**Parameters:**
- `lat1` (query, required, string) — Latitude 1 Example: `51.5074`
- `lng1` (query, required, string) — Longitude 1 Example: `-0.1278`
- `lat2` (query, required, string) — Latitude 2 Example: `48.8566`
- `lng2` (query, required, string) — Longitude 2 Example: `2.3522`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/geodistance-api/v1/midpoint?lat1=51.5074&lng1=-0.1278&lat2=48.8566&lng2=2.3522"
```

**Response:**
```json
{
    "data": {
        "lat": 50.188595,
        "lng": 1.146618
    },
    "meta": {
        "timestamp": "2026-06-03T01:09:45.194Z",
        "request_id": "116d6845-751d-419f-ab8c-1f5323a37f86"
    },
    "status": "ok",
    "message": "Midpoint",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/geodistance-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "name": "Geo Distance API",
        "notes": "Distances are great-circle (spherical earth), not road distances — for driving routes use a routing API. Nothing is stored.",
        "version": "v1",
        "endpoints": [
            {
                "path": "/v1/distance",
                "params": {
                    "lat1": "required",
                    "lat2": "required",
                    "lng1": "required",
                    "lng2": "required"
                },
                "returns": "distance (m/km/mi/nm), initial & final bearing, compass point"
            },
            {
                "path": "/v1/destination",
                "params": {
                    "lat": "required",
                    "lng": "required",
                    "unit": "m|km|mi|nm (default km)",
                    "bearing": "degrees (required)",
                    "distance": "required"
                },
                "returns": "the destination lat/lng"
            },
            {
                "path": "/v1/midpoint",
                "params": {
                    "lat1": "required",
                    "lat2": "required",
                    "lng1": "required",
                    "lng2": "required"
                },
                "returns": "the great-circle midpoint"
            },
            {
                "path": "/v1/meta",
                "params": [],
                "returns": "this document"
            }
        ],
        "
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/geodistance-api
OpenAPI spec: https://www.oanor.com/api/geodistance-api/openapi.json