Try It!

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}

where {COUNTRY_CODE} is replaced with one of the following supported country codes:

  • se (Sweden)
  • no (Norway)
  • dk (Denmark)
  • fi (Finland)

Supported parameters

Query parameterValue
api_keyRequired
A valid API key
queryRequired
The query string that will be used to filter what postcode suggestions to fetch.

Example:
query=113 Returns postcodes that begins with 113
max_rowsThe maximum number of suggestions that should be returned.
Possible values are 1 to 100.
Default value is 15.

Example: query=113&max_rows=20 Returns the first 20 postal codes in Sweden beginning with 113.
response_formatSets the format for the API response. The following values are supported:

- xml
- json (default)
- text
localityFilter results to only return addresses with a certain locality or where the locality begins with a pattern.

Example:
query=Storg&locality=Falun
query=Storg&locality=Fal*

- In case you're not providing a full locality the asterix must be used as a suffix after the locality parameter value
administrativeIncludes the administrative division relations for the postcode, based on the postcode centroid, in the response.
_ true
_ false (Default value)

See Glossary for list of supported administrative divisions in each country

Response

KeyValue TypeValue description
versionStringThe API version
suggestionsArrayAn array with zero or more suggestion objects (referenced below)
If the suggestions array is empty it means that no suggestions were found.

Status code that gives detailed information about the suggest result. This code details both general errors and detailed suggest errors.

Suggestion object

KeyValue typeValue description
postcodeStringPostal code of the address
localityStringLocality / city of the address
adm1_codeStringAdministrative division - level 1 - code
adm[1-5]_nameStringAdministrative division - level 1 - name
adm[1-5]_codeStringAdministrative division - level 2 - code

Examples

Example - A default request

curl https://app-api.geposit.se/v2.0/suggest/postcode/se -d "query=341&response_format=json&api_key={API_KEY}"
{
  "version": "2.0",
  "suggestions": [
    {
      "postcode": "34101"
    },
    {
      "postcode": "34102"
    },
    {
      "postcode": "34103"
    },
    {
      "postcode": "34104"
    },
    {
      "postcode": "34105"
    },
   ...
  ]
}

XML

TEXT
<?xml version="1.0" encoding="UTF-8"?>
<api>
    <version>2.0</version>
    <suggestions>
        <suggestion>
            <postcode>34101</postcode>
        </suggestion>
        <suggestion>
            <postcode>34102</postcode>
        </suggestion>
        <suggestion>
            <postcode>34103</postcode>
        </suggestion>
        <suggestion>
            <postcode>34104</postcode>
        </suggestion>
    </suggestions>
</api>
34101
34102
34103
34104
34105
34106
34107
34108
34109
34110
34111
34112
34114
34116
34117
34118
34120
34121
34122