Docs menu

Geocoding API endpoint

Geocoding Search API

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`.

GETapiKey1 credit/requestGeocodinggeocoding.searchResponseDoc/geocoding/search

Endpoint facts

Method: GET
API path: /geocoding/search
Auth: apiKey
Credits: 1 credit/request
Charged on: Successful 2xx responses only
Platform: Geocoding
Response schema: #/definitions/geocoding.searchResponseDoc

Geocoding API Try Geocoding Search API in Playground Geocoding API documentation

How this endpoint behaves

Returns typed Nominatim JSONv2 forward geocoding results from the public OpenStreetMap Nominatim service.

Query parameters: pass either q for free-text search or one or more structured fields: street, city, county, state, country, and postalcode. Do not combine q with structured fields. Optional parameters are limit, countrycodes, accept_language, addressdetails, extratags, and namedetails. limit defaults to 10 and is clamped to 20; addressdetails defaults to true.

Notable response behavior: empty Nominatim result sets return 404. Upstream rate limits, non-2xx responses, Nominatim error payloads, and malformed JSON return 503.

Live monitoring

Monitored request: GET /geocoding/search?limit=2&q=Empire+State+Building
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 1.52 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /geocoding/search?limit=20&q=Empire+State+Building
Items in results: 1
Fields filled in every checked item: 15

Field	Filled in, of 1 checked	Values in the sample
place_id	1
licence	1	“Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org…”
osm_type	1	“way”
osm_id	1
lat	1
lon	1
category	1	“office”
type	1	“yes”
place_rank	1	30
importance	1	0.58
addresstype	1	“office”
name	1	“Empire State Building”
display_name	1	median 138 characters
address	1
boundingbox	1	median 4 entries

Request parameters

Parameter	Type	Required	Default	Description
q	string	No		Free-text search query
street	string	No		Structured street or house number
city	string	No		Structured city
county	string	No		Structured county
state	string	No		Structured state
country	string	No		Structured country
postalcode	string	No		Structured postal code
limit	integer	No	10 and clamps to 20	Maximum results, defaults to 10 and clamps to 20
countrycodes	string	No		Comma-separated ISO 3166-1 alpha-2 country filters
accept_language	string	No		Preferred result language, forwarded to Nominatim
addressdetails	boolean	No	true	Include address details, defaults to true
extratags	boolean	No		Include OSM extra tags
namedetails	boolean	No		Include multilingual name details
x-api-key (header)	string	Yes		API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/geocoding/search?q=coffee&country=us&limit=10&addressdetails=true&extratags=true&namedetails=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "Empire State Building",
    "results": [
      {
        "place_id": 358220252,
        "osm_type": "way",
        "osm_id": 34633854,
        "lat": "40.7484421",
        "lon": "-73.9856589",
        "category": "office",
        "type": "yes",
        "place_rank": 30,
        "importance": 0.5803438355141769,
        "addresstype": "office",
        "name": "Empire State Building",
        "display_name": "Empire State Building, 350, 5th Avenue, New York, United States",
        "address": {
          "office": "Empire State Building",
          "house_number": "350",
          "road": "5th Avenue",
          "city": "New York",
          "state": "New York",
          "postcode": "10118",
          "country": "United States",
          "country_code": "us"
        },
        "boundingbox": [
          "40.7479255",
          "40.7489585",
          "-73.9865012",
          "-73.9848166"
        ]
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/geocoding.searchResponseDoc

Field	Type	Required	Example	Description
code	integer	No	200
data	geocoding.SearchResponse	No
data.query	string	No	Empire State Building	Query that was run. For a structured search, the address fields joined with commas.
data.results	array	No		Places matching the query.
data.results[].address	object	No		Structured address breakdown of the place.
data.results[].address.ISO3166-2-lvl4	string	No	US-NY	ISO 3166-2 code for the state or region level, such as `US-NY`.
data.results[].address.ISO3166-2-lvl6	string	No		ISO 3166-2 code for the level-6 administrative area, when one exists.
data.results[].address.city	string	No	New York	City of the place.
data.results[].address.country	string	No	United States	Country name of the place.
data.results[].address.country_code	string	No	us	Two-letter country code of the place in lowercase, such as `us`.
data.results[].address.county	string	No	New York County	County of the place.
data.results[].address.house_number	string	No	350	House number of the place.
data.results[].address.neighbourhood	string	No	Koreatown	Neighbourhood of the place.
data.results[].address.office	string	No	Empire State Building	Office name of the place, such as `Empire State Building`.
data.results[].address.postcode	string	No	10118	Postal code of the place.
data.results[].address.road	string	No	5th Avenue	Street name of the place.
data.results[].address.state	string	No	New York	State or region of the place.
data.results[].address.state_district	string	No		State district of the place.
data.results[].address.suburb	string	No	Manhattan	Suburb or borough of the place.
data.results[].address.town	string	No		Town of the place.
data.results[].address.village	string	No		Village of the place.
data.results[].addresstype	string	No	office	Type of address the place represents, such as `office`.
data.results[].boundingbox	array	No	40.7479255,40.7489585,-73.9865012,-73.9848166	Bounding box of the place as four decimal-degree strings: south latitude, north latitude, west longitude, east longitude.
data.results[].category	string	No	office	OpenStreetMap category of the place, such as `office`.
data.results[].display_name	string	No	Empire State Building, 350, 5th Avenue, New York, United States	Full address of the place as a comma-separated string.
data.results[].extratags	object	No		Additional OpenStreetMap tags of the place. Present only when `extratags` is requested.
data.results[].importance	number	No	0.5803438355141769	Importance score of the place; higher values mean a more prominent place.
data.results[].lat	string	No	40.7484421	Latitude of the place in decimal degrees, as a string.
data.results[].licence	string	No	Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright	Licence notice for the OpenStreetMap data.
data.results[].lon	string	No	-73.9856589	Longitude of the place in decimal degrees, as a string.
data.results[].name	string	No	Empire State Building	Name of the place.
data.results[].namedetails	object	No		Alternative names of the place. Present only when `namedetails` is requested.
data.results[].osm_id	integer	No	34633854	OpenStreetMap id of the object.
data.results[].osm_type	string	No	way	OpenStreetMap object type, such as `way`.
data.results[].place_id	integer	No	358220252	Numeric id of the place in the geocoding results.
data.results[].place_rank	integer	No	30	Address rank of the place; for example `30` for a building.
data.results[].type	string	No	yes	OpenStreetMap type of the place within its `category`, such as `yes`.
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
404	Not Found	#/definitions/app.Response
502	Bad Gateway	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/geocoding/search?q=coffee&country=us&limit=10&addressdetails=true&extratags=true&namedetails=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More Geocoding endpoint docs Geocoding API Build a Google Maps Lead Research Workflow Build an AI Agent Web Data Workflow Geocoding Lookup API documentation Geocoding Reverse API documentation

Open in Playground Back to group

Docs menu

Geocoding API endpoint

Geocoding Search API

GETapiKey1 credit/requestGeocodinggeocoding.searchResponseDoc/geocoding/search

Endpoint facts

Method: GET
API path: /geocoding/search
Auth: apiKey
Credits: 1 credit/request
Charged on: Successful 2xx responses only
Platform: Geocoding
Response schema: #/definitions/geocoding.searchResponseDoc

Geocoding API Try Geocoding Search API in Playground Geocoding API documentation

How this endpoint behaves

Returns typed Nominatim JSONv2 forward geocoding results from the public OpenStreetMap Nominatim service.

Notable response behavior: empty Nominatim result sets return 404. Upstream rate limits, non-2xx responses, Nominatim error payloads, and malformed JSON return 503.

Live monitoring

Monitored request: GET /geocoding/search?limit=2&q=Empire+State+Building
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 1.52 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /geocoding/search?limit=20&q=Empire+State+Building
Items in results: 1
Fields filled in every checked item: 15

Field	Filled in, of 1 checked	Values in the sample
place_id	1
licence	1	“Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org…”
osm_type	1	“way”
osm_id	1
lat	1
lon	1
category	1	“office”
type	1	“yes”
place_rank	1	30
importance	1	0.58
addresstype	1	“office”
name	1	“Empire State Building”
display_name	1	median 138 characters
address	1
boundingbox	1	median 4 entries

Request parameters

Parameter	Type	Required	Default	Description
q	string	No		Free-text search query
street	string	No		Structured street or house number
city	string	No		Structured city
county	string	No		Structured county
state	string	No		Structured state
country	string	No		Structured country
postalcode	string	No		Structured postal code
limit	integer	No	10 and clamps to 20	Maximum results, defaults to 10 and clamps to 20
countrycodes	string	No		Comma-separated ISO 3166-1 alpha-2 country filters
accept_language	string	No		Preferred result language, forwarded to Nominatim
addressdetails	boolean	No	true	Include address details, defaults to true
extratags	boolean	No		Include OSM extra tags
namedetails	boolean	No		Include multilingual name details
x-api-key (header)	string	Yes		API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/geocoding/search?q=coffee&country=us&limit=10&addressdetails=true&extratags=true&namedetails=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "Empire State Building",
    "results": [
      {
        "place_id": 358220252,
        "osm_type": "way",
        "osm_id": 34633854,
        "lat": "40.7484421",
        "lon": "-73.9856589",
        "category": "office",
        "type": "yes",
        "place_rank": 30,
        "importance": 0.5803438355141769,
        "addresstype": "office",
        "name": "Empire State Building",
        "display_name": "Empire State Building, 350, 5th Avenue, New York, United States",
        "address": {
          "office": "Empire State Building",
          "house_number": "350",
          "road": "5th Avenue",
          "city": "New York",
          "state": "New York",
          "postcode": "10118",
          "country": "United States",
          "country_code": "us"
        },
        "boundingbox": [
          "40.7479255",
          "40.7489585",
          "-73.9865012",
          "-73.9848166"
        ]
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/geocoding.searchResponseDoc

Field	Type	Required	Example	Description
code	integer	No	200
data	geocoding.SearchResponse	No
data.query	string	No	Empire State Building	Query that was run. For a structured search, the address fields joined with commas.
data.results	array	No		Places matching the query.
data.results[].address	object	No		Structured address breakdown of the place.
data.results[].address.ISO3166-2-lvl4	string	No	US-NY	ISO 3166-2 code for the state or region level, such as `US-NY`.
data.results[].address.ISO3166-2-lvl6	string	No		ISO 3166-2 code for the level-6 administrative area, when one exists.
data.results[].address.city	string	No	New York	City of the place.
data.results[].address.country	string	No	United States	Country name of the place.
data.results[].address.country_code	string	No	us	Two-letter country code of the place in lowercase, such as `us`.
data.results[].address.county	string	No	New York County	County of the place.
data.results[].address.house_number	string	No	350	House number of the place.
data.results[].address.neighbourhood	string	No	Koreatown	Neighbourhood of the place.
data.results[].address.office	string	No	Empire State Building	Office name of the place, such as `Empire State Building`.
data.results[].address.postcode	string	No	10118	Postal code of the place.
data.results[].address.road	string	No	5th Avenue	Street name of the place.
data.results[].address.state	string	No	New York	State or region of the place.
data.results[].address.state_district	string	No		State district of the place.
data.results[].address.suburb	string	No	Manhattan	Suburb or borough of the place.
data.results[].address.town	string	No		Town of the place.
data.results[].address.village	string	No		Village of the place.
data.results[].addresstype	string	No	office	Type of address the place represents, such as `office`.
data.results[].boundingbox	array	No	40.7479255,40.7489585,-73.9865012,-73.9848166	Bounding box of the place as four decimal-degree strings: south latitude, north latitude, west longitude, east longitude.
data.results[].category	string	No	office	OpenStreetMap category of the place, such as `office`.
data.results[].display_name	string	No	Empire State Building, 350, 5th Avenue, New York, United States	Full address of the place as a comma-separated string.
data.results[].extratags	object	No		Additional OpenStreetMap tags of the place. Present only when `extratags` is requested.
data.results[].importance	number	No	0.5803438355141769	Importance score of the place; higher values mean a more prominent place.
data.results[].lat	string	No	40.7484421	Latitude of the place in decimal degrees, as a string.
data.results[].licence	string	No	Data © OpenStreetMap contributors, ODbL 1.0. http://osm.org/copyright	Licence notice for the OpenStreetMap data.
data.results[].lon	string	No	-73.9856589	Longitude of the place in decimal degrees, as a string.
data.results[].name	string	No	Empire State Building	Name of the place.
data.results[].namedetails	object	No		Alternative names of the place. Present only when `namedetails` is requested.
data.results[].osm_id	integer	No	34633854	OpenStreetMap id of the object.
data.results[].osm_type	string	No	way	OpenStreetMap object type, such as `way`.
data.results[].place_id	integer	No	358220252	Numeric id of the place in the geocoding results.
data.results[].place_rank	integer	No	30	Address rank of the place; for example `30` for a building.
data.results[].type	string	No	yes	OpenStreetMap type of the place within its `category`, such as `yes`.
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
404	Not Found	#/definitions/app.Response
502	Bad Gateway	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/geocoding/search?q=coffee&country=us&limit=10&addressdetails=true&extratags=true&namedetails=true" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More Geocoding endpoint docs Geocoding API Build a Google Maps Lead Research Workflow Build an AI Agent Web Data Workflow Geocoding Lookup API documentation Geocoding Reverse API documentation

Open in Playground Back to group

Geocoding Search API

Endpoint facts

How this endpoint behaves

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related

Geocoding Search API

Endpoint facts

How this endpoint behaves

Live monitoring

Sampled response

Request parameters

cURL example

Example JSON response

Failure responses

Code examples

Shared guides

Related