> ## 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.

# Data model

> Overview of the data model returned by the API.

# Address structure

Addresses differ significantly between countries. Instead of forcing all countries into a single
rigid schema with many optional fields, GeoScale uses a **polymorphic data model**.

All address results share a small set of common fields that make it easy to display and work with
addresses regardless of country:

| Field         | Description                                          |
| ------------- | ---------------------------------------------------- |
| `id`          | Stable GeoScale address identifier                   |
| `type`        | Address subtype discriminator                        |
| `single_line` | Compact address formatted for display                |
| `lines`       | Multi-line address formatted for display or printing |
| `location`    | Geographic coordinates in WGS84                      |

The `type` field indicates the specific address schema used.

Country-specific address types extend the common fields with additional properties that reflect
the structure of the country's address system.

For example:

* A **Dutch street address** contains fields such as `municipality` and `province`.
* A **Luxembourg street address** contains fields such as `commune` and `canton`.

### Dutch address example

```json id="nladdr1" theme={null}
{
  "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"
  ]
}
```

### Luxembourg address example

```json id="luaddr1" theme={null}
{
  "id": "55vvgW04revtH22",
  "type": "lu_street_address",
  "house_number": "1",
  "street": "Rue du Marché-aux-Herbes",
  "postal_code": "1728",
  "locality": "Luxembourg",
  "commune": "Luxembourg",
  "canton": "Luxembourg",
  "country": "Luxembourg",
  "location": {
    "latitude": 49.611797,
    "longitude": 6.132318
  },
  "single_line": "1, Rue du Marché-aux-Herbes, Luxembourg",
  "lines": [
    "1, Rue du Marché-aux-Herbes",
    "L-1728 Luxembourg",
    "Luxembourg"
  ]
}
```

***

# Address formatting

The API provides two ready-to-use address representations:

* **`single_line`** - a compact address suitable for UI elements such as autocomplete dropdowns.

  <Card>
    Dam 1, Amsterdam
  </Card>

* **`lines`** - a multi-line representation suitable for displaying a full postal address.

  <Card>
    Dam 1<br />
    1012 JS Amsterdam<br />
    Nederland
  </Card>

These fields allow applications to display addresses immediately without needing to implement
country-specific formatting rules.

***

# Location

The `location` field contains the geographic coordinates of the address in **WGS84**.

```json id="loc1" theme={null}
"location": {
  "latitude": 52.373293,
  "longitude": 4.893718
}
```

***

# Address identifiers

Every address has a stable identifier:

```id="idfield" theme={null}
id
```

GeoScale IDs uniquely identify an address and remain stable over time.

Clients can safely **store these identifiers** and use them later to retrieve the same address using
the [lookup endpoint](/api-reference/lookup).

This allows applications to persist address selections and resolve them again
later without needing to store the full address structure.

***

# Full schema reference

This page provides a conceptual overview of the GeoScale address data model.

For the complete schema definitions of all address types and fields, see the
[API reference](/api-reference/autocomplete).