Geocoding

GET /api/geocode/search

Return coordinates based on location (city) using Nominatim API.

Scope: geocode:read

Example requests:

GET /api/geocode/search?city=Paris HTTP/1.1

Example responses:

• returning at least one location:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "locations": [
        {
          "addresstype": "suburb",
          "coordinates": "48.8588897,2.3200410",
          "display_name": "Paris, Île-de-France, France métropolitaine",
          "name": "Paris",
          "osm_id": "r7444",
        }
      ]
    },
    "status": "success"
  }

• returning no locations

HTTP/1.1 200 OK
Content-Type: application/json

  {
      "data": {
          "locations": []
      },
      "status": "success"
  }

Query Parameters:

• city (string) – location

• language (string) – preferred language for Nominatim results

Request Headers:

• Authorization – OAuth 2.0 Bearer Token

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions

  • you do not have permissions, your account is suspended

• 500 Internal Server Error –

  • error when getting coordinates from location

GET /api/geocode/lookup

Return location based on OSM id using Nominatim API.

Scope: geocode:read

Example requests:

GET /api/geocode/lookup?osm_id=r71525 HTTP/1.1

Example responses:

• returning location:

HTTP/1.1 200 OK
Content-Type: application/json

  {
    "data": {
      "location": {
        "addresstype": "suburb",
        "coordinates": "48.8588897,2.3200410",
        "display_name": "Paris, Île-de-France, France métropolitaine",
        "name": "Paris",
        "osm_id": "r7444",
        }
    },
    "status": "success"
  }

• returning no location

HTTP/1.1 200 OK
Content-Type: application/json

  {
      "data": {
          "location": {}
      },
      "status": "success"
  }

Query Parameters:

• osm_id (string) – OSM id, prefixed by location type

• language (string) – preferred language for Nominatim results

Request Headers:

• Authorization – OAuth 2.0 Bearer Token

Status Codes:

• 200 OK – success

• 401 Unauthorized –

  • provide a valid auth token

  • signature expired, please log in again

  • invalid token, please log in again

• 403 Forbidden –

  • you do not have permissions

  • you do not have permissions, your account is suspended

• 500 Internal Server Error –

  • error when getting location from OSM id