> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geoscale.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Make your first address autocomplete request with the GeoScale Address API.

## What you need

* An API key
* An HTTP client (e.g. `curl`, or any HTTP library)

To get an API key:

1. [Sign up](https://dash.geoscale.io/auth/sign-up) if you haven't already
2. On the dashboard, go to the [Billing](https://dash.geoscale.io/billing) section and choose **Add subscription**.
3. Finally, head over to the [API keys](https://dash.geoscale.io/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`:

```bash theme={null}
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

```json expandable theme={null}
{
  "hits": [
    {
      "id": "25p8hdho2ucpbSc6g1QSythIGj3dzN",
      "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, Amsterdam",
      "lines": [
        "Dam 1",
        "1012 JS Amsterdam",
        "Nederland"
      ]
    },
    {
      "id": "25p8hdho2ucRDBOUd62TKCOYqRjdXW",
      "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, Zaandam",
      "lines": [
        "Dam 1",
        "1506 BC Zaandam",
        "Nederland"
      ]
    },
    {
      "id": "25p8hdho2udLwV3DSfw84vE3hUvVtw",
      "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, Schiedam",
      "lines": [
        "Dam 1",
        "3111 BC Schiedam",
        "Nederland"
      ]
    },
    {
      "id": "25p8hdho2ucRKhDLQ09DIfnReDaY0B",
      "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, Alblasserdam",
      "lines": [
        "Dam 1",
        "2952 AB Alblasserdam",
        "Nederland"
      ]
    },
    {
      "id": "25p8hdho2udMc2spToi8mB7a3obaKu",
      "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
      },
      "single_line": "Dam 1, Goes",
      "lines": [
        "Dam 1",
        "4461 HV Goes",
        "Nederland"
      ]
    }
  ]
}
```

Each result represents a real address that can be shown to the user and selected.

## What to do next

* Continue reading the [API reference](/api-reference/autocomplete) for all parameters
* Read the [Data model](/data-model/overview) to understand how addresses are structured