Suggest Postcode

This endpoint returns suggestions of postcodes in a specific country given certain search parameters - usually used for "autocomplete" purposes to help a user type a valid postcode into a form/input field.

Endpoint URL

GET https://app-api.geposit.se/v2.0/suggest/postcode/{COUNTRY_CODE}

{COUNTRY_CODE} is se, no, dk, fi or ax. Authentication, response status and permissions are described in Valid Intro. Full reference: Suggest Postcode.

Parameters

Query parameterDescription
queryRequired. The start of the postcode. Example: query=111
max_rowsMaximum number of suggestions, 1 to 100. Default 20.
response_formatjson (default), xml or text.
administrativetrue adds administrative divisions. Needs a permission. The codes are those of one address in the postcode.
coordinatetrue adds the postcode's centre point as latitude and longitude. Needs a permission.

Response

KeyTypeDescription
versionStringAPI version
response_timeFloatProcessing time in seconds
queryObjectThe parameters as received
interpretationObjectpostcode as parsed
statusInteger302 one suggestion, 300 several, 404 none, 400 bad request (with status_text)
suggestionsArrayObjects with postcode, locality and address_type, plus adm1_code … adm5_name, latitude and longitude when requested

With response_format=text each suggestion is one line: postcode;locality.

Examples

curl -G https://app-api.geposit.se/v2.0/suggest/postcode/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "query=1112" \
  --data-urlencode "max_rows=2"
{
  "version": "2.0",
  "response_time": 0.0013,
  "query": {
    "query": "1112"
  },
  "interpretation": {
    "postcode": "1112"
  },
  "status": 300,
  "suggestions": [
    { "address_type": "NB", "postcode": "11120", "locality": "Stockholm" },
    { "address_type": "NB", "postcode": "11121", "locality": "Stockholm" }
  ]
}

The same request with response_format=xml:

<Suggest>
  <version>2.0</version>
  <response_time>0.0013</response_time>
  <query>
    <query>1112</query>
  </query>
  <interpretation>
    <postcode>1112</postcode>
  </interpretation>
  <status>300</status>
  <suggestions>
    <address_type>NB</address_type>
    <postcode>11120</postcode>
    <locality>Stockholm</locality>
  </suggestions>
  <suggestions>
    <address_type>NB</address_type>
    <postcode>11121</postcode>
    <locality>Stockholm</locality>
  </suggestions>
</Suggest>

And with response_format=text:

11120;Stockholm
11121;Stockholm

Did this page help you?