Suggest - address¶
This endpoint returns suggestions of addresses in a specific country given certain search parameters - usually used for "autocomplete" purposes to help a user type a valid address into a form/input field.
Endpoint URL¶
(POST | GET) https://valid.geposit.se/1.7/suggest/address/{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 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 - text (Default value) |
columns | A comma-separated list of what attributes you want to 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 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 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 |
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 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 |
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).
Examples¶
Example - A default request¶
curl https://valid.geposit.se/1.7/suggest/address/se -d "street=Storg&response_format=json&api_key={API_KEY}"
{
"name": "Valid API Norden",
"type": "Suggest address",
"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 address</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.7/suggest/address/se -d "street=Sal&columns=street,locality&response_format=json&api_key={API_KEY}"
{
"name": "Valid API Norden",
"type": "Suggest address",
"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 address</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