Address autocomplete

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

The address search endpoint provides type-ahead suggestions as the customer types their address. It uses an expand/resolve pattern that handles hierarchical address structures — like UK streets with many buildings — while still working simply for flat address systems.

Prerequisites

• An Ingrid API key
• An address form rendered in your checkout (see rendering the address form)

Overview

The autocomplete flow follows a tree pattern. Each prediction the API returns has an action that tells you what to do next:

• resolve — this prediction is a specific address. Call the details endpoint to get the full DeliveryAddress.
• expand — this prediction is a container (a street, a building, a postal code area). Call search again with containerId to drill down into it.

Step 1: Search for addresses

As the customer types, send their input to the search endpoint:

curl -X GET "https://api.ingrid.com/v1/delivery/address/search?countryCode=GB&query=10%20Bucking" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "predictions": [
    {
      "id": "addr_gbr_10045832",
      "label": "10 Buckingham Road",
      "secondaryLabel": "Redcar, TS10 3JQ",
      "action": "resolve",
      "type": "streetAddress"
    },
    {
      "id": "grp_street_882",
      "label": "10 Buckingham Street",
      "secondaryLabel": "3 addresses",
      "action": "expand",
      "count": 3,
      "type": "street"
    },
    {
      "id": "addr_gbr_20091744",
      "label": "10 Buckingham Gate",
      "secondaryLabel": "London, SW1E 6LB",
      "action": "resolve",
      "type": "streetAddress"
    }
  ]
}

Display the predictions as a dropdown list. Use label as the primary text and secondaryLabel as secondary context. The type field can be used to select an icon (street, building, postal code, etc.).

Step 2: Handle the action

When the customer selects a prediction, check its action:

If action is resolve

The prediction is a specific address. Proceed to Step 3.

If action is expand

The prediction is a container with child addresses. Call search again with the prediction's id as containerId:

curl -X GET "https://api.ingrid.com/v1/delivery/address/search?countryCode=GB&containerId=grp_street_882" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "predictions": [
    {
      "id": "addr_gbr_30012001",
      "label": "Flat 1, 10 Buckingham Street",
      "secondaryLabel": "London, WC2N 6DF",
      "action": "resolve",
      "type": "premise"
    },
    {
      "id": "addr_gbr_30012002",
      "label": "Flat 2, 10 Buckingham Street",
      "secondaryLabel": "London, WC2N 6DF",
      "action": "resolve",
      "type": "premise"
    },
    {
      "id": "addr_gbr_30012003",
      "label": "Flat 3, 10 Buckingham Street",
      "secondaryLabel": "London, WC2N 6DF",
      "action": "resolve",
      "type": "premise"
    }
  ]
}

Display the new predictions. The count field on the parent prediction tells you how many children to expect, which you can use to show "3 addresses" in the UI before expanding.

Expanding can be recursive — a container may contain more containers — but in practice most lookups resolve within one or two levels.

Step 3: Resolve to full address

When the customer selects a prediction with action: "resolve", call the details endpoint with its id:

curl -X GET "https://api.ingrid.com/v1/delivery/address/details/addr_gbr_10045832" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

{
  "deliveryAddress": {
    "countryCode": "GB",
    "postalCode": "TS10 3JQ",
    "addressLines": ["10 Buckingham Road"],
    "locality": "Redcar"
  }
}

Step 4: Populate the form

Map the returned DeliveryAddress fields to your form inputs. The field names in the response match the field names from the form endpoint, so the mapping is direct.

After populating, allow the customer to review and edit the pre-filled values before proceeding.

The focus parameter

The optional focus parameter scopes autocomplete behavior to a specific form field. This is useful when the customer is editing an individual field rather than typing a full address:

curl -X GET "https://api.ingrid.com/v1/delivery/address/search?countryCode=GB&query=SW1A&focus=postalCode" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Debouncing and performance

The search endpoint is designed for real-time use, but you should still debounce requests on the client side. A 200-300ms debounce after the last keystroke prevents excessive API calls without hurting perceived responsiveness.

Do not call search with fewer than 2-3 characters — the results will be too broad to be useful.

Error handling

Prediction IDs are opaque and may expire. If a details call returns 404, prompt the customer to search again.

Next steps

• Address validation — verify the resolved address before creating an order
• Country reference — country-specific addressing rules