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}
{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