Skip to content

Suggest - street


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

Endpoint URL

(POST | GET) https://valid.geposit.se/1.6/suggest/street/{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 street / street address suggestions to fetch.

Example:
query=Storg Returns street names/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
- text (Default value)
columns A comma-separated list of address attributes that should be part of the resulting suggestions.
Possible values are:
- street
- street_number
- letter
- extra_number
- 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=Storg&columns=street,street_number,letter,postalcode,locality
postalcode Filter results to only return street names/addresses with a certain postalcode or where the postalcode begins with a pattern.

Example:
query=Storg&postalcode=11217
query=Storg&postalcode=112*

* In case you're not providing a full postalcode the asterix must be used as a suffix after the postalcode parameter value
locality Filter results to only return street names/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 street names/addresses with a certain street number.

Example:
query=Storg&street_number=12
extra_number Filter results to only return street names/addresses with a certain secondary street number.

Example:
query=Landsvägen&street_number=12&extra_number=102
letter Filter results to only return street names/addresses with a certain letter.

Example:
query=Storgatan&street_number=12&letter=A

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
street String Street name
street_number String Street number
extra_number String Additional/extra street number *
* Some street names/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
postalcode String Postal code of the address
locality String Locality / city of the address
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/street/se -d "street=Storg&response_format=json&api_key={API_KEY}"
{
  "name": "Valid API Norden",
  "type": "Suggest street",
  "version": "latest",
  "charset": "utf-8",
  "suggestions": [
    {
      "street": "Storgatan",
      "street_number": "1",
      "extra_number": "",
      "letter": "",
      "postalcode": "11444",
      "locality": "Stockholm"
    },
    {
      "street": "Storgatan",
      "street_number": "1",
      "extra_number": "",
      "letter": "",
      "postalcode": "15172",
      "locality": "Södertälje"
    },
    {
      "street": "Storgatan",
      "street_number": "1",
      "extra_number": "",
      "letter": "",
      "postalcode": "15330",
      "locality": "Järna"
    },
   ...
  ]
}
<?xml version="1.0" encoding="UTF-8"?>
<api>
    <name>Valid API Norden</name>
    <type>Suggest street</type>
    <version>latest</version>
    <charset>utf-8</charset>
    <suggestions>
        <suggestion>
            <street>Storgatan</street>
            <street_number>1</street_number>
            <extra_number></extra_number>
            <letter></letter>
            <postalcode>11444</postalcode>
            <locality>Stockholm</locality>
        </suggestion>
        <suggestion>
            <street>Storgatan</street>
            <street_number>1</street_number>
            <extra_number></extra_number>
            <letter></letter>
            <postalcode>15172</postalcode>
            <locality>Södertälje</locality>
        </suggestion>
        <suggestion>
            <street>Storgatan</street>
            <street_number>1</street_number>
            <extra_number></extra_number>
            <letter></letter>
            <postalcode>15330</postalcode>
            <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://valid.geposit.se/1.6/suggest/street/se -d "street=Sal&columns=street,locality&response_format=json&api_key={API_KEY}"
{
  "name": "Valid API Norden",
  "type": "Suggest street",
  "version": "latest",
  "charset": "utf-8",
  "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>
 <name>Valid API Norden</name>
 <type>Suggest street</type>
 <version>latest</version>
 <charset>utf-8</charset>
 <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