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.6/suggest/locality/{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 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.6/suggest/locality/se -d "query=Sto&response_format=json&api_key={API_KEY}"

JSON

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

<?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>

TEXT

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.6/suggest/locality/se -d "query=Sto&columns=locality,adm2_code,adm2&response_format=json&api_key={API_KEY}"

JSON

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

<?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>

TEXT

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