API reference

# Search

Find coordinates and structured address components from a free-text address or place. A partial match may return goodMatch: false (or omit it). An empty object means nothing was found.

Runnable examples: [Node.js geocoding guide →](https://opengeocoding.com/geocoding-nodejs) [Python guide →](https://opengeocoding.com/geocoding-python)

1 credit per successful call · Authentication and account rate limit apply.

POST GET /v1/search

## Request body

`application/json` · Up to 64 KiB. Unknown fields are rejected. Send your key in [x-api-key](https://opengeocoding.com/docs/authentication). With GET, send the same fields as URL query parameters instead; nested fields use dots, such as `focus.lat`. Unknown or repeated parameters return 400\. The key still goes in a header.

* `addressString` string required  
Free-text address or place. Trimmed before searching; cannot be blank.  
Up to 500 characters.

## Response 200

Default scalar values and empty lists may be omitted. Treat absent lists as empty and absent scalars as their protobuf defaults.

* `addressDetails` AddressDetails  

  * `aerialway` string
  * `aeroway` string
  * `allotments` string
  * `amenity` string
  * `borough` string
  * `boundary` string
  * `bridge` string
  * `city` string
  * `cityBlock` string
  * `cityDistrict` string
  * `club` string
  * `commercial` string
  * `continent` string
  * `country` string
  * `countryCode` string
  * `county` string
  * `craft` string
  * `croft` string
  * `district` string
  * `emergency` string
  * `farm` string
  * `farmyard` string
  * `hamlet` string
  * `highway` string
  * `historic` string
  * `houseName` string
  * `houseNumber` string
  * `industrial` string
  * `isolatedDwelling` string
  * `landuse` string
  * `leisure` string
  * `manMade` string
  * `military` string
  * `mountainPass` string
  * `municipality` string
  * `natural` string
  * `neighbourhood` string
  * `office` string
  * `place` string
  * `postcode` string
  * `province` string
  * `quarter` string
  * `railway` string
  * `region` string
  * `regionCodes` ISO3166\_2\[\]  
  ISO 3166-2 codes for the address.

    * `adminLevel` integer  
      Administrative level.  
      Range: 0–4294967295.
    * `code` string  
      ISO 3166-2 region code.
  * `regions` Region\[\]  
  Administrative regions for the address.

    * `adminCode` string  
      ISO 3166-2 administrative region code.
    * `adminLevel` integer  
      Administrative level.  
      Range: 0–4294967295.
    * `countryCode` string  
      ISO 3166-1 alpha-2 country code.
    * `countryName` string  
      Country name.
    * `enName` string  
      English region name.
    * `localName` string  
      Local region name.
    * `parentAdminCode` string  
      Parent administrative region code, when available.
  * `residential` string
  * `retail` string
  * `road` string
  * `shop` string
  * `state` string
  * `stateDistrict` string
  * `subdivision` string
  * `suburb` string
  * `tourism` string
  * `town` string
  * `tunnel` string
  * `village` string
  * `waterway` string
* `displayName` string  
Human-readable address or place name.
* `geoCoordinates` GeoCoordinates  

  * `boundingBox` BoundingBox  

    * `maxLat` number  
      Northern latitude in degrees.
    * `maxLon` number  
      Eastern longitude in degrees.
    * `minLat` number  
      Southern latitude in degrees.
    * `minLon` number  
      Western longitude in degrees.
  * `lat` number  
  Latitude in degrees, from -90 to 90\. Omission uses the protobuf default of 0.
  * `lon` number  
  Longitude in degrees, from -180 to 180\. Omission uses the protobuf default of 0.
* `goodMatch` boolean  
True for a good match. False or omitted for a partial match, such as a street without the requested house number.

## Errors

| HTTP | Code                | Meaning                                                                                                                                                                                                                                                                                                    |
| ---- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | invalid\_argument   | Invalid JSON, unknown fields, unknown or repeated query parameters, unsupported Connect protocol version, oversized body, invalid query or unverifiable client address.                                                                                                                                    |
| 401  | unauthenticated     | The API key is missing, invalid, expired or revoked.                                                                                                                                                                                                                                                       |
| 403  | permission\_denied  | A browser key was used without an Origin header, from an origin not in its allowed list, or over gRPC.                                                                                                                                                                                                     |
| 404  | not\_found          | The suggestion ID is unknown or belongs to an older index. Request autocomplete suggestions again.                                                                                                                                                                                                         |
| 429  | resource\_exhausted | The per-second limit was reached, a billable operation has no remaining credits, or the client IP is temporarily locked after failed API authentication. Autocomplete and regions remain available with zero credits. IP lockouts include Retry-After and also block valid keys from that IP until expiry. |
| 503  | unavailable         | The API is starting or the geocoder is temporarily unavailable.                                                                                                                                                                                                                                            |

[Error handling and retries →](https://opengeocoding.com/docs/errors)

## Make a request

Example language

cURL 

```
curl 'https://api.opengeocoding.com/v1/search' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "addressString": "10 Rue de Rivoli, 75004 Paris"
}'
```

The production API base URL is `https://api.opengeocoding.com`. Keep secret keys server-side; in web pages, use a [browser key](https://opengeocoding.com/docs/authentication#browser-keys). JavaScript example uses Node.js; Python uses only the standard library.

## GET request

cURL 

```
curl --get 'https://api.opengeocoding.com/v1/search' \
  -H 'x-api-key: YOUR_API_KEY' \
  --data-urlencode 'addressString=10 Rue de Rivoli, 75004 Paris'
```

## Example response

200 · application/json 

```
{
  "addressDetails": {
    "city": "Paris",
    "country": "France",
    "countryCode": "fr",
    "houseNumber": "10",
    "postcode": "75004",
    "road": "Rue de Rivoli"
  },
  "displayName": "Example address",
  "geoCoordinates": {
    "lat": 48.855,
    "lon": 2.36
  },
  "goodMatch": true
}
```

Illustrative data, not a measured API result.

Build with your own tools

Import the OpenAPI specification into Postman, Insomnia or a client generator.

[Download openapi.json ↓](https://opengeocoding.com/openapi.json)

Canonical page: https://opengeocoding.com/docs/search