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

{
  "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

{
  "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.
Dam 1, Amsterdam
lines - a multi-line representation suitable for displaying a full postal address.
Dam 1
1012 JS Amsterdam
Nederland

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.

"location": {
  "latitude": 52.373293,
  "longitude": 4.893718
}

Address identifiers

Every address has a stable identifier:

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

Getting started

Using the API

API reference

Data model

Address structure

Dutch address example

Luxembourg address example

Address formatting

Location

Address identifiers

Full schema reference

​Address structure

​Dutch address example

​Luxembourg address example

​Address formatting

​Location

​Address identifiers

​Full schema reference

Address structure

Dutch address example

Luxembourg address example

Address formatting

Location

Address identifiers

Full schema reference