Suggest Address

Endpoint URL

(GET) https://app-api.geposit.se/v2.0/suggest/address/{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 address suggestions to fetch. Example: query=Storg Returns addresses that begins with Storg
max_rows	The maximum number of suggestions that should be returned. Possible values are 1 to 100. Default value is 15. Example: query=Storg&max_rows=20 Returns 20 streets in Sweden beginning with storg.
response_format	Sets the format for the API response. The following values are supported: _ xml _ json (default) * text
postcode	Filter results to only return addresses with a certain postcode or where the postcode begins with a pattern. Example: query=Storg&postcode=11217 query=Storg&postcode=112* * In case you're not providing a full postcode the asterix must be used as a suffix after the postcode parameter value
locality	Filter 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
street_number	Filter results to only return addresses with a certain street number. Example: query=Storg&street_number=12
extra_number	Filter results to only return addresses with a certain secondary street number. Example: query=Landsvägen&street_number=12&extra_number=102
letter	Filter results to only return addresses with a certain letter. Example: query=Storgatan&street_number=12&letter=A
administrative	Includes the administrative division relations for the address in the response. _ true _ false (Default value) See Glossary for list of supported administrative divisions in each country
coordinate	Includes the coordinate for the address in the response. _ true _ false (Default value)
property_designation	Includes property designation for Swedish addresses (Fastighetsbeteckning). true false (Default value)
uuid	Includes the uuid for the address in the response. _ true _ false (Default value)
group	Returns results as groups of suggestions. (A group is a collection of suggstion objects). _ true _ false (Default value) Example Group Object: { "address_type": "NC", "street": "Aareavaara", "postcode": "98491", "locality": "Pajala", "group_path": "lps\|Pajala\|98491\|Aareavaara", "group_count": 70 },
group_path	Filter results to only return addresses within a certain group. Example: query=Aa&group_path=lps\|Pajala\|98491\|Aareavaara
street_number_prefix	Ensures that the response strictly focuses on only considering the prefix values of street numbers when matching the provided street number. Example: When 10 is sent as the street number, _ true Will return addresses with street numbers such as, 10,105,1005 _ false (Default value) Will return addresses only with the street number as 10.

Note
To be able to request uuid attribute, you need to have a specific permission.

Response

Key	Value Type	Value description
version	String	The API version
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
street	String	Street name
street_number	String	Street number
extra_number	String	Additional/extra street number * * Some addresses have dual street number attributing, e.g. Landsbyvägen 2-220. In these cases street_number will be 2 and extra_number will be 220
letter	String	Letter used in street number attribution, e.g. Storgatan 12A
postcode	String	Postal code of the address
locality	String	Locality / city of the address
latitude	Float	Latitude of the address if existing
longitude	Float	Longitude of the address if existing
property_designation	String	Includes property designation for Swedish addresses (Fastighetsbeteckning).
adm_code	String	Administrative code for levels 1-5 See Glossary for list of supported administrative divisions in each country
adm_name	String	Administrative name for levels 1-5 See Glossary for list of supported administrative divisions in each country

Note
Sometimes, you might see an additional parameters like street_alt and locality_alt in the response for suggestion requests against Finland (country code: fi). These attributes represent the alternative street name and alternative locality names which comes in Swedish language.

Also it is possible to use Swedish address names on suggestion requests against Finland (country code: fi).

Localisation object


locale	String	Locale for this translation
street	String	Translation for street
locality	String	Translation for locality

Examples

Example - A default request

curl https://app-api.geposit.se/v2.0/suggest/address/se -d "query=Storg&response_format=json&api_key={API_KEY}"

{
  "version": "2.0",
  "suggestions": [
    {
      "street": "Storgatan",
      "street_number": "1",
      "extra_number": "",
      "letter": "",
      "postcode": "11444",
      "locality": "Stockholm"
    },
    {
      "street": "Storgatan",
      "street_number": "1",
      "extra_number": "",
      "letter": "",
      "postcode": "15172",
      "locality": "Södertälje"
    },
    {
      "street": "Storgatan",
      "street_number": "1",
      "extra_number": "",
      "letter": "",
      "postcode": "15330",
      "locality": "Järna"
    },
   ...
  ]
}

XML

TEXT

<?xml version="1.0" encoding="UTF-8"?>
<api>
    <version>2.0</version>
    <suggestions>
        <suggestion>
            <street>Storgatan</street>
            <street_number>1</street_number>
            <extra_number></extra_number>
            <letter></letter>
            <postcode>11444</postcode>
            <locality>Stockholm</locality>
        </suggestion>
        <suggestion>
            <street>Storgatan</street>
            <street_number>1</street_number>
            <extra_number></extra_number>
            <letter></letter>
            <postcode>15172</postcode>
            <locality>Södertälje</locality>
        </suggestion>
        <suggestion>
            <street>Storgatan</street>
            <street_number>1</street_number>
            <extra_number></extra_number>
            <letter></letter>
            <postcode>15330</postcode>
            <locality>Järna</locality>
        </suggestion>
    </suggestions>
</api>

Storgatan;1;;;11444;Stockholm
Storgatan;1;;;15172;Södertälje
Storgatan;1;;;15330;Järna
Storgatan;1;;;21141;Malmö
Storgatan;1;;;23197;Klagstorp
Storgatan;1;;;23331;Svedala
Storgatan;1;;;23940;Falsterbo
Storgatan;1;;;24130;Eslöv
Storgatan;1;;;24172;Marieholm
Storgatan;1;;;24231;Hörby
Storgatan;1;;;24330;Höör
Storgatan;1;;;24531;Staffanstorp

Example - Controlling what attributes to retrieve in the suggestions

curl https://app-api.geposit.se/v2.0/suggest/address/se -d "street=Sal&columns=street,locality&response_format=json&api_key={API_KEY}"

{
  "version": "2.0",
  "suggestions": [
    {
      "street": "Sal",
      "locality": "Strängnäs"
    },
    {
      "street": "Sala",
      "locality": "Delsbo"
    },
    {
      "street": "Salabacksgatan",
      "locality": "Uppsala"
    },
    {
      "street": "Salaboda",
      "locality": "Nora"
    },
    {
      "street": "Salaboda Stensbo",
      "locality": "Nora"
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<api>
 <version>2.0</version>
 <suggestions>
  <suggestion>
   <street>Sal</street>
   <locality>Strängnäs</locality>
  </suggestion>
  <suggestion>
   <street>Sala</street>
   <locality>Delsbo</locality>
  </suggestion>
  <suggestion>
   <street>Salabacksgatan</street>
   <locality>Uppsala</locality>
  </suggestion>
  <suggestion>
   <street>Salaboda</street>
   <locality>Nora</locality>
  </suggestion>
  <suggestion>
   <street>Salaboda Stensbo</street>
   <locality>Nora</locality>
  </suggestion>
 </suggestions>
</api>

Sal;Strängnäs
Sala;Delsbo
Salabacksgatan;Uppsala
Salaboda;Nora
Salaboda Stensbo;Nora
Sala Erikslund;Sala
Sala Finnbo;Möklinta
Sala flygplats;Sala
Salagatan;Enköping
Salagatan;Spånga
Salagatan;Uppsala
SALAKULLEVÄGEN;Varberg
Salamandergatan;Färjestaden
Salamandervägen;Gävle
Salamandervägen;Torslanda
Salamandervägen;Västerås
Salamandervägen;Örebro
Salamisvägen;Ängelholm
Sala Prästgård;Sala
Salarp;Älmestad