---
title: "Search Nominatim places"
method: GET
path: "/geocoding/search"
tags: ["Geocoding"]
---

# Search Nominatim places

`GET /geocoding/search`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/geocoding/search`
- Auth: API key in header `x-api-key`

Searches OpenStreetMap places by address. Pass either free-text `q` or structured fields (`street`, `city`, `county`, `state`, `country`, `postalcode`), not both. `limit` defaults to 10 and is clamped to 20; `countrycodes` restricts by ISO 3166-1 alpha-2 country. Each result has its display name, coordinates, category, type, bounding box, importance and address parts. No match returns `404`.

## Query parameters

- `q` string
- `street` string
- `city` string
- `county` string
- `state` string
- `country` string
- `postalcode` string
- `limit` integer
- `countrycodes` string
- `accept_language` string
- `addressdetails` boolean
- `extratags` boolean
- `namedetails` boolean

## Headers

- `x-api-key` string, required

## Response `200`

OK

- GeocodingSearchResponseDoc
  - `code` integer
  - `data` GeocodingSearchResponse
    - `query` string: Query that was run. For a structured search, the address fields joined with commas.
    - `results` GeocodingPlace[]: Places matching the query.
      - `address` GeocodingAddress
        - `ISO3166-2-lvl4` string: ISO 3166-2 code for the state or region level, such as `US-NY`.
        - `ISO3166-2-lvl6` string: ISO 3166-2 code for the level-6 administrative area, when one exists.
        - `city` string: City of the place.
        - `country` string: Country name of the place.
        - `country_code` string: Two-letter country code of the place in lowercase, such as `us`.
        - `county` string: County of the place.
        - `house_number` string: House number of the place.
        - `neighbourhood` string: Neighbourhood of the place.
        - `office` string: Office name of the place, such as `Empire State Building`.
        - `postcode` string: Postal code of the place.
        - `road` string: Street name of the place.
        - `state` string: State or region of the place.
        - `state_district` string: State district of the place.
        - `suburb` string: Suburb or borough of the place.
        - `town` string: Town of the place.
        - `village` string: Village of the place.
      - `addresstype` string: Type of address the place represents, such as `office`.
      - `boundingbox` string[]: Bounding box of the place as four decimal-degree strings: south latitude, north latitude, west longitude, east longitude.
      - `category` string: OpenStreetMap category of the place, such as `office`.
      - `display_name` string: Full address of the place as a comma-separated string.
      - `extratags` object: Additional OpenStreetMap tags of the place. Present only when `extratags` is requested.
      - `importance` number: Importance score of the place; higher values mean a more prominent place.
      - `lat` string: Latitude of the place in decimal degrees, as a string.
      - `licence` string: Licence notice for the OpenStreetMap data.
      - `lon` string: Longitude of the place in decimal degrees, as a string.
      - `name` string: Name of the place.
      - `namedetails` object: Alternative names of the place. Present only when `namedetails` is requested.
      - `osm_id` integer: OpenStreetMap id of the object.
      - `osm_type` string: OpenStreetMap object type, such as `way`.
      - `place_id` integer: Numeric id of the place in the geocoding results.
      - `place_rank` integer: Address rank of the place; for example `30` for a building.
      - `type` string: OpenStreetMap type of the place within its `category`, such as `yes`.
  - `msg` string

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `502`: Bad Gateway
- `503`: Service Unavailable

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/028417aa35bb?raw)