Skip to main content

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.

​
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:
FieldDescription
idStable GeoScale address identifier
typeAddress subtype discriminator
single_lineCompact address formatted for display
linesMulti-line address formatted for display or printing
locationGeographic 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.