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.7/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.7/suggest/street/se -d "street=Storg&response_format=json&api_key={API_KEY}"

JSON

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

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

TEXT

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.7/suggest/street/se -d "street=Sal&columns=street,locality&response_format=json&api_key={API_KEY}"

JSON

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

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

TEXT

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