Suggest Services

Suggest Zipcode

The Suggest Zipcode endpoint suggests postal codes at locality level (L) or at street level (S, available for GBR, IRL, NLD, and JPN).

Endpoint

POSThttps://{host}:{port}/Egon/api/suggest/zipcode

Headers & authentication

Required request headers and their expected values.

Field	Type	Description
`token`req	String	Authentication token sent in the `token` request header.

Request

Country context, extraction level, and postal code query.

Field	Type	Description
`par`req	Object	Processing parameters, candidate limits, and country context
`iso2`	String	Country code, ISO 3166-1 alpha-2. One of `iso2` or `iso3` is required.
`iso3`	String	Country code, ISO 3166-1 alpha-3. One of `iso2` or `iso3` is required.
`max_candidates`	Number	Maximum number of candidates to extract Default value: `10`
`data`req	Object	Search criteria for postal code lookup
`query`req	String	Query string
`zip_level`	String	Extraction level: `L` for locality-level candidates, or `S` for street-level candidates. Street-level extraction is used in GBR, IRL, NLD, and JPN. Default: `L` Default value: `L`

Response

Matching postal codes, associated localities or streets, and system status.

Field	Type	Description
`data`	Object
`results`	Array	Array of candidate matches returned by the suggestion engine
`country`	String	Country name
`country_id`	Number	ID of the country
`state`	String	State name
`state_code`	String	State code
`state_id`	Number	ID of the state
`region`	String	Region name
`region_code`	String	Region code
`region_id`	Number	ID of the region
`province`	String	Province name
`province_code`	String	Province code
`province_id`	Number	ID of the province
`city`	String	City name
`city_id`	Number	ID of the city
`district1`	String	First-level district name
`district1_id`	Number	ID of the first-level district
`street`	String	Street name
`street_id`	Number	ID of the street
`number`	String	House number
`exponent`	String	Exponent
`zipcode`	String	Postal code
`building`	String	Building name; available only for GBR and IRL
`subbuilding`	String	Sub-building information; available only for GBR and IRL
`organization`	String	Organization name; available only for GBR and IRL
`system`	Object	System error and execution status
`ret_code`	Number	Code: 0 no blocking error, <> 0 blocking error code
`des_ret_code`	String	Description

On this page

Endpoint
Headers & authentication
Request
Response

Request Example

curl -X POST "https://{host}:{port}/Egon/api/suggest/zipcode" \
  -H "token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "par": {
    "iso3": "ITA"
  },
  "data": {
    "query": "37135"
  }
}'

Endpoint​

Headers & authentication​

Request​

Response​

Endpoint

Headers & authentication

Request

Response