Geocode an address
Geocoder.geocode
Convert one structured address with a required city to coordinates and matching address details.
Body parameters
| Body | Type | Description |
|---|---|---|
address | object REQUIRED | Provide an address object with city. Other fields are optional; include enough detail to find a match. |
country | string | Optional country code. Omitted or null defaults to PL; an empty value remains empty. Use uppercase PL for Polish addresses. International geocoding requires access to international coverage. |
province | string | Optional province name; no value is filled in automatically. |
district | string | Optional. Missing or null defaults to an empty string. |
community | string | Optional. Missing or null defaults to an empty string. |
city | string REQUIRED | Required city name for every address, including PL. |
quarter | string | Optional. Missing or null defaults to an empty string. |
pcode | string | Optional. Missing or null defaults to an empty string. |
street | string | Optional. Missing or null defaults to an empty string. |
house | string | Optional. Missing or null defaults to an empty string. |
maxResult | integer | For PL addresses, maximum matches per address: 1–3 (default 1). Values outside this range are limited to 1–3. Set maxResult in each address; maxResults does not set this limit. |
Example request
{
"address": {
"country": "PL",
"city": "Warszawa",
"street": "Domaniewska",
"house": "37"
}
}Example response
{
"result": [
{
"quality": 9,
"x": 21.0071318,
"y": 52.18284,
"country": "PL",
"province": "mazowieckie",
"district": "Warszawa",
"community": "Warszawa",
"city": "Warszawa",
"quarter": "Mokotów",
"pcode": "02-672",
"street": "Domaniewska",
"house": "37",
"resultRadius": 0,
"flat": ""
}
]
}The example shows selected response fields. Actual coordinates and postal-code data depend on the input and current map data; entitlement-dependent extended fields may also be present.
result fields
| result fields | Type | Description |
|---|---|---|
quality | integer | Geocoding quality score. |
x | double | Longitude (WGS84). |
y | double | Latitude (WGS84). |
country | string | Country code. |
province | string | Province. |
district | string | District (powiat). |
community | string | Community (gmina). |
city | string | City. |
quarter | string | Quarter. |
pcode | string | Postal code (PL only). |
street | string | Street. |
house | string | House number. |
addressType | integer EXTENDED | Building type. Extended. |
peoplesForAddress | integer EXTENDED | Residents at address. Extended. |
flatsForAddress | integer EXTENDED | Flats at address. Extended. |
buildingsForAddress | integer EXTENDED | Buildings at address. Extended. |
pcodeExtraInfo | object[] EXTENDED | Extra postal-code info. Extended. |
resultRadius | number | Result envelope radius (m). -1 if unknown. |
mapLink | string | Link to map result. |