Documentation > Geolocation

API - Postal codes and addresses (postal_codes)

Geolocation

Finds postal codes and street addresses, from free text or from a country and a city.

Endpointhttps://api.opensolr.com/solr_manager/api/postal_codes
MethodGET or POST
Authemail and api_key of your account, as GET or POST parameters: Authentication.

01 · Parameters

queryOne of the two

Free text, up to 120 characters: a postal code, 10115 Berlin, Bacau Romania.

country + cityOne of the two

A country and a city, with street, number and state if you want.

limitOptional

How many of each kind, 1 to 50. Default 10.

02 · Example

curl -s "https://api.opensolr.com/solr_manager/api/postal_codes?email=YOUR_EMAIL&api_key=YOUR_API_KEY" --data-urlencode "query=10115 Berlin" -d "limit=3"

03 · Answer

{
    "status": true,
    "contract_version": 1,
    "query": {
        "zip_query": "10115 Berlin"
    },
    "postal_codes": [
        {
            "postal_code": "10115",
            "place": "Berlin",
            "region": "Berlin",
            "country": "Germany",
            "country_code": "DE",
            "lat": 52.5323,
            "lon": 13.3846
        }
    ],
    "addresses": []
}

postal_codes lists the matching codes with their place, addresses the matching street addresses. Values shown are an example.

04 · Errors

ERROR_NO_POSTAL_QUERYHTTP 200

No query, and not both country and city.

ERROR_GEO_NO_DATAHTTP 200

Nothing found.

ERROR_GEO_LOOKUP_UNAVAILABLEHTTP 200

The data could not be asked. Retry later.

WRONG_API_HOSTHTTP 404

Called on opensolr.com. The answer carries the right URL.

ERROR_AUTHENTICATION_FAILEDHTTP 403

The email and API key do not match.

ERROR_RATE_LIMIT_PER_MINUTEHTTP 429

Too many calls. Wait for the Retry-After seconds.

Each call counts once toward your per-minute and per-hour limits, whatever the number of items: Rate limits. Lookups never use the AI allowance.

05 · Related

Addresses to coordinates: address_geo.

Every error code and HTTP status of the API: API errors. Calls per minute and per hour: Rate limits.