getAddressDetails (v1)

Retrieve complete address details from provider

Query GET tag:Address Search Connector

Overview

Internal endpoint called by address-search-api to retrieve full address details using a provider-specific address ID. The connector must transform the provider’s detailed response into Plumery’s standard address model.

GET (/internal/v1/address-suggestions/{addressId})

Parameters

  • addressId (path) (required): Provider-specific address identifier (from search results)

Responses

200 OK

Complete standardised address details. Connectors must map provider-specific fields to this standard Plumery address model. Fields may be null if the provider doesn’t supply that data.

404 Not Found

500 Internal Server Error

Architecture

16 properties

Complete standardised address details. Connectors must map provider-specific fields to this standard Plumery address model. Fields may be null if the provider doesn't supply that data.

id string
required

Provider-specific address identifier

address string

Formatted address string suitable for display

streetName string

Name of a street or thoroughfare

buildingNumber string

Number that identifies the position of a building on a street

buildingName string

Name of the building or house

floor string

Floor or storey within a building

postBox string

Post office box number

suite string

Building room number or apartment number

postCode string

Postal code identifier

townName string

Name of a built-up area with defined boundaries

townLocationName string

Specific location name within the town

districtName string

Subdivision within a country sub-division

countrySubDivision string

State, region, county, or other country subdivision

country string
required

ISO alpha-2 country code

Min length: 2
Max length: 2
language string

ISO alpha-2 language code indicating the language used for formatting this address. Reflects the actual language used by the provider to format field values. Connectors should return the language code if known, or null if provider doesn't support language selection.

Match pattern: ^[a-z]{2}$
Min length: 2
Max length: 2
additionalData object

Provider-specific additional data that doesn't map to standard fields. Stored as key-value pairs for potential future use or debugging.

5 properties
code string
required

Standard error code. Connectors should translate provider errors to these codes: - INVALID_REQUEST - Bad request parameters - PROVIDER_ERROR - Provider returned an error - PROVIDER_UNAVAILABLE - Cannot reach provider - RATE_LIMIT_EXCEEDED - Provider rate limit hit - AUTHENTICATION_FAILED - Provider authentication failed - ADDRESS_NOT_FOUND - Address ID not found - INTERNAL_ERROR - Connector internal error

message string
required

Human-readable error message

requestId string

Unique request identifier for debugging

providerErrorCode string

Original provider-specific error code (for debugging)

providerErrorMessage string

Original provider error message (for debugging)

5 properties
code string
required

Standard error code. Connectors should translate provider errors to these codes: - INVALID_REQUEST - Bad request parameters - PROVIDER_ERROR - Provider returned an error - PROVIDER_UNAVAILABLE - Cannot reach provider - RATE_LIMIT_EXCEEDED - Provider rate limit hit - AUTHENTICATION_FAILED - Provider authentication failed - ADDRESS_NOT_FOUND - Address ID not found - INTERNAL_ERROR - Connector internal error

message string
required

Human-readable error message

requestId string

Unique request identifier for debugging

providerErrorCode string

Original provider-specific error code (for debugging)

providerErrorMessage string

Original provider error message (for debugging)