# MeshCore Tools API

All endpoints are versioned under `/api/v1/`.

Base URL on production: `https://meshcore.envoyage.io/api/v1/`

---

## `POST /cities/get_by_lat_lon`

Finds the single closest Dutch place to the given latitude/longitude, and returns its full city-database record plus the distance from the query point.

### Request
**Method:** `POST`
**Content-Type:** `application/x-www-form-urlencoded` *or* `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `access_key` | string | yes | A shared secret from the server's allowlist. |
| `lat` | number | yes | Query latitude in WGS84 decimal degrees. Valid range: `-90 … 90`. |
| `lon` | number | yes | Query longitude in WGS84 decimal degrees. Valid range: `-180 … 180`. |

### Example

```bash
curl -X POST https://meshcore.envoyage.io/api/v1/cities/get_by_lat_lon \
  -d "access_key=YOUR_KEY&lat=53.2205&lon=6.5710"
```

### Successful response

`200 OK`, `Content-Type: application/json`. Example:

```json
{
  "ok": true,
  "city": {
    "name": "Groningen",
    "placeLocode": "GRQ",
    "provinceName1": "Groningen",
    "provinceCode1": "nl-gr",
    "provinceName2": "Drenthe",
    "provinceCode2": "nl-dr",
    "provinceName3": "",
    "provinceCode3": "",
    "lat": 53.2191,
    "lon": 6.568,
    "radiusM": 5163,
    "municipalityName": "Groningen",
    "municipalityLocode": "GRQ",
    "placeCode": "nl-gr-grq",
    "municipalityCode": "nl-gr-grq",
    "broaderName1": "Groningen",
    "broaderRegion1": "nl-grq",
    "broaderName2": "",
    "broaderRegion2": "",
    "broaderName3": "",
    "broaderRegion3": "",
    "broaderName4": "",
    "broaderRegion4": "",
    "groupName1": "Noord",
    "groupCode1": "nl-noord",
    "groupName2": "",
    "groupCode2": "",
    "groupName3": "",
    "groupCode3": "",
    "isHub": true
  },
  "distance_m": 252.88
}
```



---




## `POST /regions/get_by_lat_lon`

Finds the single closest Dutch place to the given latitude/longitude, and returns the MeshCore *region suggestions* (the same hierarchy and command list the `/regions` tool renders visually for the matched place).

### Request

**Method:** `POST`
**Content-Type:** `application/x-www-form-urlencoded` *or* `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `access_key` | string | yes | A shared secret from the server's allowlist. |
| `lat` | number | yes | Query latitude in WGS84 decimal degrees. Valid range: `-90 … 90`. |
| `lon` | number | yes | Query longitude in WGS84 decimal degrees. Valid range: `-180 … 180`. |

### Example

```bash
curl -X POST https://meshcore.envoyage.io/api/v1/regions/get_by_lat_lon \
  -d "access_key=YOUR_KEY&lat=53.2205&lon=6.5710"
```

### Successful response

`200 OK`, `Content-Type: application/json`. Example:

```json
{
  "ok": true,
  "place": {
    "name": "Groningen",
    "provinces": ["Groningen", "Drenthe"],
    "municipality": "Groningen"
  },
  "home": "nl-gr-grq",
  "default": "nl-gr",
  "regions": [
    { "code": "eu",        "name": "Europa",    "parent": null,    "type": "continent" },
    { "code": "nl",        "name": "Nederland", "parent": null,    "type": "country"   },
    { "code": "nl-gr",     "name": "Groningen", "parent": "nl",    "type": "province"  },
    { "code": "nl-dr",     "name": "Drenthe",   "parent": "nl",    "type": "province"  },
    { "code": "nl-grq",    "name": "Groningen", "parent": "nl",    "type": "broader"   },
    { "code": "nl-noord",  "name": "Noord",     "parent": "nl",    "type": "group"     },
    { "code": "nl-gr-grq", "name": "Groningen", "parent": "nl-gr", "type": "place"     }
  ],
  "commands": [
    "region put eu",
    "region put nl",
    "region put nl-gr nl",
    "region put nl-dr nl",
    "region put nl-grq nl",
    "region put nl-noord nl",
    "region put nl-gr-grq nl-gr",
    "region allowf eu",
    "region allowf nl",
    "region allowf nl-gr",
    "region allowf nl-dr",
    "region allowf nl-grq",
    "region allowf nl-noord",
    "region allowf nl-gr-grq",
    "region default nl-gr",
    "region home nl-gr-grq",
    "region save"
  ],
  "distance_m": 252.88
}
```