Addresses

Overview

The addresses service has three different endpoints for different use cases.

• Typeahead Search: Fast address suggestions for checkout forms, registration workflows, and autocomplete functionality. Returns essential address information optimized for user interface components including unique address identifiers for form handling.
• Retrieve Address: Retrieve a single address by its unique identifier.
• Advanced Search: Advanced address search with filtering and field projection capabilities. Ideal for complex queries requiring detailed address information with geographic coordinates and municipality data.

Typeahead Search

The typeahead search endpoint (/search) provides fast address suggestions optimized for autocomplete functionality. This endpoint is designed for real-time user interface components where speed is critical.

Endpoint

GET /addresses/search?q={query}

Parameters

• q (required): Search query (address name, postal code, or postal office)

Example Request

GET /addresses/search?q=Mannerheimintie

Example Response

{
  "hits": [
    {
      "id": "b75f82f3-4075-461a-b033-aa35724a3155",
      "addressFin": "Mannerheimintie 1",
      "addressSwe": "Mannerheimvägen 1",
      "addressNameFin": "Mannerheimintie",
      "addressNameSwe": "Mannerheimvägen",
      "numberPartOfAddressNumber": 71,
      "postalCode": "00100",
      "postalOfficeFin": "Helsinki",
      "postalOfficeSwe": "Helsingfors",
      "domicileCode": "091",
      "country": "FI"
    }
  ],
  "estimatedTotalHits": 1,
  "processingTimeMs": 15,
  "source": "Suomen ympäristökeskuksen (Syke)"
}

Retrieve Address

The retrieve address endpoint (/{address_id}) returns detailed information for a specific address including building data.

Endpoint

GET /addresses/{id}

Parameters

• id (required): Unique address identifier

Example Request

GET /addresses/b75f82f3-4075-461a-b033-aa35724a3155

Example Response

{
  "id": "b75f82f3-4075-461a-b033-aa35724a3155",
  "addressFin": "Mannerheimintie 1",
  "addressSwe": "Mannerheimvägen 1",
  "addressNameFin": "Mannerheimintie",
  "addressNameSwe": "Mannerheimvägen",
  "numberPartOfAddressNumber": 71,
  "postalCode": "00100",
  "postalOfficeFin": "Helsinki",
  "postalOfficeSwe": "Helsingfors",
  "municipalityNumber": "091",
  "domicileCode": "091",
  "coordinates": {
    "longitude": 24.945831,
    "latitude": 60.169856
  },
  "country": "FI",
  "buildings": [
    {
      "id": "building-uuid-123",
      "buildingKey": "building-key-123",
      "permanentBuildingIdentifier": "PERM123456",
      "propertyIdentifier": "PROP789",
      "completionDate": "2020-01-15",
      "demolitionDate": null,
      "mainPurpose": {
        "id": "purpose-1",
        "descriptionFi": "Asuinrakennus",
        "descriptionSv": "Bostadshus",
        "descriptionEn": "Residential building"
      },
      "usageStatus": {
        "id": "purpose-1",
        "descriptionFi": "Asuinrakennus",
        "descriptionSv": "Bostadshus",
        "descriptionEn": "Residential building"
      },
      "facadeMaterial": {
        "id": "purpose-1",
        "descriptionFi": "Asuinrakennus",
        "descriptionSv": "Bostadshus",
        "descriptionEn": "Residential building"
      },
      "heatingMethod": {
        "id": "purpose-1",
        "descriptionFi": "Asuinrakennus",
        "descriptionSv": "Bostadshus",
        "descriptionEn": "Residential building"
      },
      "heatingEnergySource": {
        "id": "purpose-1",
        "descriptionFi": "Asuinrakennus",
        "descriptionSv": "Bostadshus",
        "descriptionEn": "Residential building"
      },
      "materialLoadBearing": {
        "id": "purpose-1",
        "descriptionFi": "Asuinrakennus",
        "descriptionSv": "Bostadshus",
        "descriptionEn": "Residential building"
      },
      "constructionMethod": {
        "id": "purpose-1",
        "descriptionFi": "Asuinrakennus",
        "descriptionSv": "Bostadshus",
        "descriptionEn": "Residential building"
      },
      "protectionMethod": {
        "id": "purpose-1",
        "descriptionFi": "Asuinrakennus",
        "descriptionSv": "Bostadshus",
        "descriptionEn": "Residential building"
      },
      "volume": 15000.5,
      "numberOfStoreys": 8,
      "grossFloorArea": 2500.75,
      "totalArea": 2200.25,
      "floorArea": 2000,
      "apartmentCount": 16,
      "isAccessible": true,
      "votingDistrictNumber": "001",
      "cultureHistoricalSignificance": null,
      "coordinates": {
        "longitude": 24.945831,
        "latitude": 60.169856
      },
      "pointLocationSrid": 4326,
      "modifiedTimestampUtc": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Advanced Search

The advanced search endpoint (/search/advanced) provides filtering and field projection capabilities for sophisticated address queries. This allows you to create precise searches that return exactly the data you need.

Endpoint

POST /addresses/search/advanced

Request Body

{
  "query": "Mannerheimintie Helsinki",
  "filters": ["postalCode = 00100"],
  "fields": "id,addressFin,postalCode,coordinates",
  "limit": 5
}

Example Response

{
  "hits": [
    {
      "id": "b75f82f3-4075-461a-b033-aa35724a3155",
      "addressFin": "Mannerheimintie 1",
      "postalCode": "00100",
      "coordinates": {
        "longitude": 24.945831,
        "latitude": 60.169856
      }
    }
  ],
  "estimatedTotalHits": 1,
  "processingTimeMs": 15,
  "query": "Mannerheimintie Helsinki",
  "limit": 5,
  "offset": 0,
  "hasMore": false,
  "source": "Suomen ympäristökeskuksen (Syke)"
}

Usage Examples

For information about data sources and update frequencies, see the Data documentation.

Response Fields

Address Fields

Field	Type	Description
id	string	Unique address identifier
addressFin	string	Complete address in Finnish
addressSwe	string|null	Complete address in Swedish
addressNameFin	string	Street name in Finnish
addressNameSwe	string|null	Street name in Swedish
numberPartOfAddressNumber	number	House/building number
postalCode	string	Postal code
postalOfficeFin	string	Postal office in Finnish
postalOfficeSwe	string	Postal office in Swedish
municipalityNumber	string	Municipality number
domicileCode	string	Municipality code (same as domicileCode in companies)
country	string	Country code (FI)
coordinates	object	Geographic coordinates
buildings	array	Array of building objects associated with this address

Building Fields

Field	Type	Description
id	string	Unique building identifier
buildingKey	string	Building key
permanentBuildingIdentifier	string	Permanent building identifier
propertyIdentifier	string	Property identifier
completionDate	string	Building completion date
demolitionDate	string|null	Building demolition date
mainPurpose	object	Building's main purpose
usageStatus	object	Current usage status
facadeMaterial	object	Facade material
heatingMethod	object	Heating method
heatingEnergySource	object	Heating energy source
materialLoadBearing	object	Load-bearing material
constructionMethod	object	Construction method
protectionMethod	object|null	Protection method
volume	number	Building volume
numberOfStoreys	number	Number of storeys
grossFloorArea	number	Gross floor area
totalArea	number	Total area
floorArea	number	Floor area
apartmentCount	number	Number of apartments
isAccessible	boolean|null	Accessibility status
votingDistrictNumber	string	Voting district number
cultureHistoricalSignificance	string|null	Cultural/historical significance
coordinates	object	Building coordinates
pointLocationSrid	number	Point location SRID
modifiedTimestampUtc	string	Last modified timestamp (UTC)
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp