Skip to main content

​
What you need

  • An API key
  • An HTTP client (e.g. curl, or any HTTP library)
To get an API key:
  1. Sign up if you haven’t already
  2. On the dashboard, go to the Billing section and choose Add subscription.
  3. Finally, head over to the API keys section and click Create API key.
All requests must include your API key as a Bearer token.

​
Make your first request

Send a GET request to the autocomplete endpoint with a country code and a partial address query. Example using curl: 
curl "https://api.geoscale.io/v1/address?country=NL&q=dam+1&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
In this example:
  • country specifies the country to search in
  • q is the partial address input typed by the user
  • limit controls how many suggestions are returned

​
Example response

{
  "country": "NL",
  "language": "nl",
  "hits": [
    {
      "single_line": "Dam 1, Amsterdam",
      "lines": [
        "Dam 1",
        "1012 JS Amsterdam",
        "Nederland"
      ],
      "record": {
        "type": "nl_street_address",
        "street": "Dam",
        "house_number": "1",
        "postal_code": "1012 JS",
        "locality": "Amsterdam",
        "municipality": "Amsterdam",
        "province": "Noord-Holland",
        "country": "Nederland"
      },
      "location": {
        "latitude": 52.373293,
        "longitude": 4.893718
      }
    },
    {
      "single_line": "Dam 1, Zaandam",
      "lines": [
        "Dam 1",
        "1506 BC Zaandam",
        "Nederland"
      ],
      "record": {
        "type": "nl_street_address",
        "street": "Dam",
        "house_number": "1",
        "postal_code": "1506 BC",
        "locality": "Zaandam",
        "municipality": "Zaanstad",
        "province": "Noord-Holland",
        "country": "Nederland"
      },
      "location": {
        "latitude": 52.439496,
        "longitude": 4.825241
      }
    },
    {
      "single_line": "Dam 1, Schiedam",
      "lines": [
        "Dam 1",
        "3111 BC Schiedam",
        "Nederland"
      ],
      "record": {
        "type": "nl_street_address",
        "street": "Dam",
        "house_number": "1",
        "postal_code": "3111 BC",
        "locality": "Schiedam",
        "municipality": "Schiedam",
        "province": "Zuid-Holland",
        "country": "Nederland"
      },
      "location": {
        "latitude": 51.917776,
        "longitude": 4.395723
      }
    },
    {
      "single_line": "Dam 1, Alblasserdam",
      "lines": [
        "Dam 1",
        "2952 AB Alblasserdam",
        "Nederland"
      ],
      "record": {
        "type": "nl_street_address",
        "street": "Dam",
        "house_number": "1",
        "postal_code": "2952 AB",
        "locality": "Alblasserdam",
        "municipality": "Alblasserdam",
        "province": "Zuid-Holland",
        "country": "Nederland"
      },
      "location": {
        "latitude": 51.858704,
        "longitude": 4.660075
      }
    },
    {
      "single_line": "Dam 1, Goes",
      "lines": [
        "Dam 1",
        "4461 HV Goes",
        "Nederland"
      ],
      "record": {
        "type": "nl_street_address",
        "street": "Dam",
        "house_number": "1",
        "postal_code": "4461 HV",
        "locality": "Goes",
        "municipality": "Goes",
        "province": "Zeeland",
        "country": "Nederland"
      },
      "location": {
        "latitude": 51.501864,
        "longitude": 3.890381
      }
    }
  ],
  "limit": 5
}
Each result represents a real address that can be shown to the user and selected.

​
What to do next

  • Continue reading the API reference for all parameters
  • Read the Data model to understand how addresses are structured