Suggest - locality¶
This endpoint returns suggestions of localities in a specific country given certain search parameters - usually used for "autocomplete" purposes to help a user type a valid locality into a form/input field.
Endpoint URL¶
(POST | GET) https://valid.geposit.se/1.7/suggest/locality/{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 locality suggestions to fetch. Example: query=Sto Returns localities that begins with Sto |
max_rows | The maximum number of suggestions that should be returned. Possible values are 1 to 100. Default value is 15. Example: query=Sto&max_rows=20 Returns the first 20 localities that begins with Sto . |
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: - locality - adm1_code - Administrative division - level 1 - code ¹- adm1 - Administrative division - level 1 - name¹- adm2_code - Administrative division - level 2 - code¹- adm2 - Administrative division - level 2 - name¹- adm3_code - Administrative division - level 3 - code¹- adm3 - Administrative division - level 3 - name¹- adm4_code - Administrative division - level 4 - code¹- adm4 - Administrative division - level 4 - name¹- adm5_code - Administrative division - level 5 - code¹- adm5 - Administrative division - level 5 - name¹>Example: query=Sto&columns=locality,adm2_code,adm2 |
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 |
---|---|---|
locality | String | Locality |
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/locality/se -d "query=Sto&response_format=json&api_key={API_KEY}"
{
"name": "Valid API Norden",
"type": "Suggest locality",
"version": "latest",
"charset": "utf-8",
"suggestions": [
{
"locality": "Stoby"
},
{
"locality": "Stocka"
},
{
"locality": "Stockamöllan"
},
{
"locality": "Stockaryd"
},
{
"locality": "Stockholm"
...
]
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
<name>Valid API Norden</name>
<type>Suggest locality</type>
<version>latest</version>
<charset>utf-8</charset>
<suggestions>
<suggestion>
<locality>Stoby</locality>
</suggestion>
<suggestion>
<locality>Stocka</locality>
</suggestion>
<suggestion>
<locality>Stockamöllan</locality>
</suggestion>
<suggestion>
<locality>Stockaryd</locality>
</suggestion>
<suggestion>
<locality>Stockholm</locality>
</suggestion>
</suggestions>
</api>
Stoby
Stocka
Stockamöllan
Stockaryd
Stockholm
Stockholm-Arlanda
Stockholm-Globen
Stocksund
Stora Blåsjön
Stora Höga
Stora Levene
Stora Mellösa
Stora Skedvi
Stora Sundby
Stora Vika
Storebro
Storfors
Storlien
Storseleby
Storsjö Kapell
Example - Controlling what attributes to retrieve in the suggestions¶
curl https://valid.geposit.se/1.7/suggest/locality/se -d "query=Sto&columns=locality,adm2_code,adm2&response_format=json&api_key={API_KEY}"
{
"name": "Valid API Norden",
"type": "Suggest locality",
"version": "latest",
"charset": "utf-8",
"suggestions": [
{
"locality": "Stoby",
"adm2_code": "1293",
"adm2": "Hässleholm"
},
{
"locality": "Stocka",
"adm2_code": "2132",
"adm2": "Nordanstig"
},
{
"locality": "Stockamöllan",
"adm2_code": "1285",
"adm2": "Eslöv"
},
{
"locality": "Stockamöllan",
"adm2_code": "1267",
"adm2": "Höör"
},
...
]
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
<name>Valid API Norden</name>
<type>Suggest locality</type>
<version>latest</version>
<charset>utf-8</charset>
<suggestions>
<suggestion>
<locality>Stoby</locality>
<adm2_code>1293</adm2_code>
<adm2>Hässleholm</adm2>
</suggestion>
<suggestion>
<locality>Stocka</locality>
<adm2_code>2132</adm2_code>
<adm2>Nordanstig</adm2>
</suggestion>
<suggestion>
<locality>Stockamöllan</locality>
<adm2_code>1285</adm2_code>
<adm2>Eslöv</adm2>
</suggestion>
</api>
Stoby;1293;Hässleholm
Stocka;2132;Nordanstig
Stockamöllan;1285;Eslöv
Stockamöllan;1267;Höör
Stockaryd;0683;Värnamo
Stockaryd;0684;Sävsjö
Stockholm;0180;Stockholm
Stockholm;0138;Tyresö
Stockholm;0186;Lidingö
Stockholm-Arlanda;0191;Sigtuna
Stockholm-Globen;0180;Stockholm
Stocksund;0162;Danderyd
Stora Blåsjön;2313;Strömsund
Stora Höga;1415;Stenungsund
Stora Levene;1470;Vara
Stora Levene;1494;Lidköping
Stora Mellösa;1880;Örebro
Stora Skedvi;2083;Hedemora
Stora Skedvi;2082;Säter
Stora Skedvi;2080;Falun