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