Skip to content

Geocoding Search

Search for addresses and locations using OpenStreetMap Nominatim geocoding service. Public endpoint.

Endpoint

GET /v1/accounts/geocoding/search/

Authentication

Not required (public endpoint)

Query Parameters

Parameter Type Required Description
q string Yes Search query (address, place name, etc.)
limit integer No Maximum number of results (1-10, default: 5)

Response

Success (200 OK)

Returns an array of search results from Nominatim:

[
  {
    "place_id": 123456789,
    "licence": "Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright",
    "osm_type": "way",
    "osm_id": 123456789,
    "boundingbox": ["40.365", "40.375", "49.835", "49.845"],
    "lat": "40.37",
    "lon": "49.84",
    "display_name": "Baku, Azerbaijan",
    "class": "place",
    "type": "city",
    "importance": 0.9,
    "address": {
      "city": "Baku",
      "country": "Azerbaijan",
      "country_code": "az"
    }
  }
]

Error Responses

Bad Request (400)

{
  "error": "Query parameter 'q' is required"
}

Internal Server Error (500)

{
  "error": "Failed to fetch from geocoding service"
}

or

{
  "error": "Failed to read response"
}

or

{
  "error": "Failed to parse response"
}

Example Request

curl -X GET "https://api.luxmart.site/v1/accounts/geocoding/search/?q=Baku&limit=5"

Notes

  • This endpoint proxies requests to OpenStreetMap Nominatim geocoding service
  • Results are limited to 1-10 items (default: 5)
  • The limit parameter is validated and clamped to the valid range
  • Results include detailed address information when available
  • This is a public endpoint, no authentication required
  • The service uses a 10-second timeout for external requests