Skip to content

Search

Request

Search for addresses or expand a container to drill down into child results.

Returns a list of address predictions based on the user's text input or hierarchical container expansion.

The "Expand vs Resolve" Pattern

Each prediction in the response has an action field that determines the next step:

  • resolve: The prediction is a final address. Call GET /v1/address/details/{id} with the prediction's id to get the full address.
  • expand: The prediction is a container (e.g., a building with multiple units). Call this endpoint again with containerId set to the prediction's id to fetch the children.

Usage Modes

  1. Text Search: Provide query with the user's typed text. Results are ranked by relevance.
  2. Container Drill-Down: Provide containerId from a previous prediction (where action was expand). The query parameter is ignored in this mode.
  3. Field-Specific Search: Use the focus parameter to optimize results for the field being edited (e.g., postalCode triggers postal database lookups in supported countries).
Security
BearerAuth
Query
countryCodestring(Address.CountryCode)^[A-Z]{2}$required

ISO 3166-1 alpha-2 country code.

siteIdstring, non-empty(Address.SiteId)required

Site identifier, referring to which site the autocompletion is performed for.

querystring

The text typed by the user. Ignored if containerId is provided.

containerIdstring

The ID of a parent result (where action was expand). Used to fetch children (e.g., units in a building).

focusstring(Address.AutocompleteFocus)

The field the user is currently editing. Helps the API optimize results. For example, if focus is postalCode and the country is GB, the API searches the PAF database.

Enum:"addressLines""postalCode""locality""administrativeArea"
curl -i -X GET \
  'https://docs.ingrid.com/_mock/developer-resources/ingrid-api/openapi/v1/address/search?countryCode=NO&siteId=00000000-0000-0000-0000-000000000000&query=string&containerId=string&focus=addressLines' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The request has succeeded.

Bodyapplication/json
predictionsArray of objects(Address.Prediction)required

List of address predictions matching the search query or container expansion.

Response

Returns street containers and resolvable addresses in the Netherlands

{
  "predictions": [
    { … },
    { … }
  ]
}