Skip to content

Suggest - postalcode


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

Endpoint URL

(POST | GET) https://valid.geposit.se/1.7/suggest/postalcode/{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 parameter Value
api_key Required
A valid API key
query Required
The query string that will be used to filter what postalcode suggestions to fetch.

Example:
query=113 Returns postalcodes that begins with 113
max_rows The 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_format Sets the format for the API response. The following values are supported:
- xml
- json
- text (Default value)
columns A comma-separated list of what attributes you want to be part of the resulting suggestions.
Possible values are:
- postalcode
- locality
- adm1_code - Numeric county code (variable differs by country)
- adm1 - County (variable differs by country)
- adm2_code - Numeric Municipality code (variable differs by country)
- adm2 - Municipality (variable differs by country)

Example:
query=113&columns=postalcode,locality
locality Filter results to only return postalcodes with a certain locality or where the locality begins with a pattern.

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

* In case you're not providing a full locality the asterix must be used as a suffix after the locality parameter value

Response

Key Value type Value description
name String The name of the API
type String The type of service used, in this case "Suggest"
version String The API version
charset String The character encoding of the response, always utf-8
suggestions Array An array with zero or more suggestion objects (referenced below)
If the suggestions array is empty it means that no suggestions were found.

If an invalid request was sent suggestions will be replaced with a status_code and status_text attribute. - status (Integer)
Status code that gives detailed information about the suggest result. This code details both general errors and detailed suggest errors.

  • status_text (String)
    The description of the corresponding status code that gives detailed information about the suggest result.

Suggestion object

Key Value type Value description
postalcode String Postal code
locality String Locality / city of the postalcode
adm1_code String Administrative division - level 1 - code
adm1 String Administrative division - level 1 - name
adm2_code String Administrative division - level 2 - code
adm2 String Administrative division - level 2 - name

Examples

Example - A default request

curl https://valid.geposit.se/1.7/suggest/postalcode/se -d "query=341&response_format=json&api_key={API_KEY}"
{
  "name": "Valid API Norden",
  "type": "Suggest postalcode",
  "version": "latest",
  "charset": "utf-8",
  "suggestions": [
    {
      "postalcode": "34101"
    },
    {
      "postalcode": "34102"
    },
    {
      "postalcode": "34103"
    },
    {
      "postalcode": "34104"
    },
    {
      "postalcode": "34105"
    },
   ...
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
    <name>Valid API Norden</name>
    <type>Suggest postalcode</type>
    <version>latest</version>
    <charset>utf-8</charset>
    <suggestions>
        <suggestion>
            <postalcode>34101</postalcode>
        </suggestion>
        <suggestion>
            <postalcode>34102</postalcode>
        </suggestion>
        <suggestion>
            <postalcode>34103</postalcode>
        </suggestion>
        <suggestion>
            <postalcode>34104</postalcode>
        </suggestion>
    </suggestions>
</api>
34101
34102
34103
34104
34105
34106
34107
34108
34109
34110
34111
34112
34114
34116
34117
34118
34120
34121
34122

Example - Controlling what attributes to retrieve in the suggestions

curl https://valid.geposit.se/1.7/suggest/postalcode/se -d "query=632&columns=postalcode,locality&response_format=json&api_key={API_KEY}"
{
  "name": "Valid API Norden",
  "type": "Suggest postalcode",
  "version": "latest",
  "charset": "utf-8",
  "suggestions": [
    {
      "postalcode": "64201",
      "locality": "Flen"
    },
    {
      "postalcode": "64206",
      "locality": "Malmköping"
    },
    {
      "postalcode": "64220",
      "locality": "Flen"
    },
    {
      "postalcode": "64221",
      "locality": "Flen"
    },
    {
      "postalcode": "64222",
      "locality": "Flen"
    },
    ...
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
 <name>Valid API Norden</name>
 <type>Suggest postalcode</type>
 <version>latest</version>
 <charset>utf-8</charset>
 <suggestions>
  <suggestion>
   <postalcode>64201</postalcode>
   <locality>Flen</locality>
  </suggestion>
  <suggestion>
   <postalcode>64206</postalcode>
   <locality>Malmköping</locality>
  </suggestion>
  <suggestion>
   <postalcode>64220</postalcode>
   <locality>Flen</locality>
  </suggestion>
  <suggestion>
   <postalcode>64221</postalcode>
   <locality>Flen</locality>
  </suggestion>
  <suggestion>
   <postalcode>64222</postalcode>
   <locality>Flen</locality>
  </suggestion>
</api>
64201;Flen
64206;Malmköping
64220;Flen
64221;Flen
64222;Flen
64223;Flen
64224;Flen
64228;Flen
64231;Flen
64232;Flen
64233;Flen
64234;Flen
64235;Flen
64236;Flen
64237;Flen
64260;Malmköping
64261;Malmköping
64262;Bettna
64281;Flen
64282;Flen