Suggest Locality

Endpoint URL

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

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

Parameters

Query parameter	Description
`query`	Required. The start of the locality name. Example: `query=Stock`
`max_rows`	Maximum number of suggestions, 1 to 100. Default 20.
`response_format`	`json` (default), `xml` or `text`.
`administrative`	`true` adds administrative divisions. Needs a permission. The codes are those of one address in the locality.
`coordinate`	`true` adds the locality's centre point as `latitude` and `longitude`. Needs a permission.

Response

Key	Type	Description
`version`	String	API version
`response_time`	Float	Processing time in seconds
`query`	Object	The parameters as received
`interpretation`	Object	`locality` as parsed
`status`	Integer	`302` one suggestion, `300` several, `404` none, `400` bad request (with `status_text`)
`suggestions`	Array	Objects with `locality` and `address_type`, plus `adm1_code` … `adm5_name`, `latitude` and `longitude` when requested

With response_format=text each suggestion is one line with the locality.

Examples

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

{
  "version": "2.0",
  "response_time": 0.0023,
  "query": {
    "query": "Stock"
  },
  "interpretation": {
    "locality": "Stock"
  },
  "status": 300,
  "suggestions": [
    { "address_type": "NB", "locality": "Stocka" },
    { "address_type": "NB", "locality": "Stockamöllan" },
    { "address_type": "NC", "locality": "Stockaryd" },
    { "address_type": "BB", "locality": "Stockholm" },
    { "address_type": "BB", "locality": "Stockholm-Arlanda" },
    { "address_type": "BB", "locality": "Stockholm-Globen" },
    { "address_type": "BB", "locality": "Stocksund" }
  ]
}

With administrative=true&coordinate=true each suggestion also carries the divisions and the centre point:

{
  "address_type": "NB",
  "locality": "Stocka",
  "adm1_code": "21",
  "adm2_code": "2132",
  "adm3_code": "213202",
  "adm4_code": "318035",
  "adm5_code": "213202",
  "adm1_name": "Gävleborg",
  "adm2_name": "Nordanstig",
  "adm3_name": "Nordanstigskustens församling",
  "adm4_name": "Harmånger",
  "adm5_name": "Harmånger-Jättendal",
  "latitude": 61.89409,
  "longitude": 17.35891
}