Suggest Address

Endpoint URL

GET https://app-api.geposit.se/v2.0/suggest/address/{COUNTRY_CODE}

{COUNTRY_CODE} is se, no, dk, fi or ax. Authentication, response status and permissions are described in Valid Intro. Full reference: Suggest Address.

Parameters

Query parameter	Description
`query`	Required (unless `group_path` is used). What the user has typed so far. Example: `query=Drottninggatan 4`
`max_rows`	Maximum number of suggestions, 1 to 100. Default 20. A higher value returns `"status": 400`.
`response_format`	`json` (default), `xml` or `text`.
`postcode`	Only addresses in this postcode. A trailing `` matches the start: `postcode=114`.
`locality`	Only addresses in this locality. A trailing `` matches the start: `locality=Fal`.
`street_number`	Only this street number. Example: `query=Storgatan&street_number=12`
`street_number_prefix`	`true` also returns street numbers that start with `street_number`: 1 then matches 1, 10, 11, 100 … Default `false`.
`letter`	Only this letter. Example: `query=Storgatan&street_number=12&letter=A`
`extra_number`	Only this secondary street number.
`group`	`true` returns one suggestion per street and postcode, with a `group_path` and a `group_count`, instead of one per address. See Grouping.
`group_path`	With `group=true`: the `group_path` of a group, to list the addresses in it.
`administrative`	`true` adds administrative divisions. Needs a permission.
`coordinate`	`true` adds `latitude` and `longitude`. Needs a permission.
`property_designation`	`true` adds the property designation, Sweden. Needs a permission.
`uuid`	`true` adds the address's unique id, Sweden only. Needs a permission.
`deso`	`true` adds `deso_code`, Sweden. Needs a permission.
`regso`	`true` adds `regso_code` and `regso_name`, Sweden. Needs a permission.
`neighborhood`	`true` adds `neighborhood_1_name` and `neighborhood_2_name`. Needs a permission.

A request without query (and without group_path) is answered with HTTP 400 and "status": 400.

Response

Key	Type	Description
`version`	String	API version
`response_time`	Float	Processing time in seconds
`query`	Object	The parameters as received
`interpretation`	Object	How `query` was parsed: `street`, `street_number`, `letter`, `postcode`, `locality`
`status`	Integer	`302` one suggestion, `300` several, `404` none, `400` bad request (with `status_text`)
`suggestions`	Array	The suggested addresses

Suggestion object

Empty fields are left out.

Key	Type	Description
`address_type`	String	See Address types
`street`	String	Street name
`street_number`	String	Street number
`letter`	String	Letter of the street number
`extra_number`	String	Secondary street number
`postcode`	String	Postcode
`locality`	String	Locality
`group_path`, `group_count`	String, Integer	With `group=true`: the group's id and the number of addresses in it
`adm1_code` … `adm5_code`, `adm1_name` … `adm5_name`	String	With `administrative=true`
`latitude`, `longitude`	Float	With `coordinate=true`
`property_designation`, `uuid`, `deso_code`, `regso_code`, `regso_name`, `neighborhood_1_name`, `neighborhood_2_name`	String	With the matching parameter

With response_format=text each suggestion is one line: street;street_number;extra_number;letter;postcode;locality.

Finland

Suggest Address finds Finnish addresses by their Finnish and their Swedish names: query=Mannerheimvägen 1 returns Mannerheimvägen … Helsingfors. Note that Validate Address only accepts the Finnish names.

Examples

Autocomplete

curl -G https://app-api.geposit.se/v2.0/suggest/address/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "query=Drottninggatan 4" \
  --data-urlencode "locality=Stockholm"

{
  "version": "2.0",
  "response_time": 0.0037,
  "query": {
    "query": "Drottninggatan 4",
    "locality": "Stockholm"
  },
  "interpretation": {
    "street": "Drottninggatan",
    "street_number": "4",
    "locality": "Stockholm"
  },
  "status": 302,
  "suggestions": [
    {
      "address_type": "NB",
      "street": "Drottninggatan",
      "street_number": "4",
      "postcode": "11151",
      "locality": "Stockholm"
    }
  ]
}

Text format

curl -G https://app-api.geposit.se/v2.0/suggest/address/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "query=Drottningg" \
  --data-urlencode "max_rows=3" \
  --data-urlencode "response_format=text"

Drottninggatan;45;;;11121;Stockholm
Drottninggatan;45;;T;11121;Stockholm
Drottninggatan;50;;;11121;Stockholm

Grouping

For rural areas with many addresses on one street, grouping lets the user pick the street first. Ask for groups:

curl -G https://app-api.geposit.se/v2.0/suggest/address/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "query=Aa" \
  --data-urlencode "group=true"

{
  "status": 300,
  "suggestions": [
    {
      "address_type": "NC",
      "street": "Aapuajoki",
      "postcode": "95794",
      "locality": "Övertorneå",
      "group_path": "lps|Övertorneå|95794|Aapuajoki",
      "group_count": 110
    },
    {
      "address_type": "NC",
      "street": "Aareavaara",
      "postcode": "98491",
      "locality": "Pajala",
      "group_path": "lps|Pajala|98491|Aareavaara",
      "group_count": 70
    }
  ]
}

Then list the addresses in the group the user picked. Send group=true together with its group_path:

curl -G https://app-api.geposit.se/v2.0/suggest/address/se \
  -H "x-api-key: {API_KEY}" \
  --data-urlencode "query=Aa" \
  --data-urlencode "group=true" \
  --data-urlencode "group_path=lps|Pajala|98491|Aareavaara"

{
  "status": 300,
  "suggestions": [
    {
      "address_type": "NC",
      "street": "Aareavaara",
      "street_number": "3",
      "postcode": "98491",
      "locality": "Pajala",
      "group_path": "lpsn|Pajala|98491|Aareavaara|3|"
    },
    {
      "address_type": "NC",
      "street": "Aareavaara",
      "street_number": "6",
      "postcode": "98491",
      "locality": "Pajala",
      "group_path": "lpsn|Pajala|98491|Aareavaara|6|"
    }
  ]
}

(version, response_time, query and interpretation left out, and the lists shortened.)