{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer-resources/ingrid-api/guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Address autocomplete","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"address-autocomplete","__idx":0},"children":["Address autocomplete"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An Ingrid API key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An address form rendered in your checkout (see"," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-form"},"children":["rendering the address form"]},")"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":2},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The autocomplete flow follows a tree pattern. Each prediction the API returns"," ","has an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}," that tells you what to do next:"]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"flowchart TD\n A[Customer types in address field] --> B[GET /address/search]\n B --> C{Check action}\n C -->|resolve| D[GET /address/details/id]\n D --> E[Populate form fields]\n C -->|expand| F[GET /address/search with containerId]\n F --> C\n","diagramHtml":"

resolve

expand

Customer types in address field

GET /address/search

Check action

GET /address/details/id

Populate form fields

GET /address/search with containerId

"},"children":["flowchart TD\n A[Customer types in address field] --> B[GET /address/search]\n B --> C{Check action}\n C -->|resolve| D[GET /address/details/id]\n D --> E[Populate form fields]\n C -->|expand| F[GET /address/search with containerId]\n F --> C\n"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resolve"]}]}," — this prediction is a specific address. Call the details"," ","endpoint to get the full ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DeliveryAddress"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expand"]}]}," — this prediction is a container (a street, a building, a postal"," ","code area). Call search again with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["containerId"]}," to drill down into it."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-search-for-addresses","__idx":3},"children":["Step 1: Search for addresses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As the customer types, send their input to the search endpoint:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"Request","header":{"title":"Request","controls":{"copy":{}}},"source":"curl -X GET \"https://api.ingrid.com/v1/delivery/address/search?countryCode=GB&query=10%20Bucking\" \\\n -H \"Authorization: Bearer \"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Response","header":{"title":"Response","controls":{"copy":{}}},"source":"{\n \"predictions\": [\n {\n \"id\": \"addr_gbr_10045832\",\n \"label\": \"10 Buckingham Road\",\n \"secondaryLabel\": \"Redcar, TS10 3JQ\",\n \"action\": \"resolve\",\n \"type\": \"streetAddress\"\n },\n {\n \"id\": \"grp_street_882\",\n \"label\": \"10 Buckingham Street\",\n \"secondaryLabel\": \"3 addresses\",\n \"action\": \"expand\",\n \"count\": 3,\n \"type\": \"street\"\n },\n {\n \"id\": \"addr_gbr_20091744\",\n \"label\": \"10 Buckingham Gate\",\n \"secondaryLabel\": \"London, SW1E 6LB\",\n \"action\": \"resolve\",\n \"type\": \"streetAddress\"\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Display the predictions as a dropdown list. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}," as the primary text"," ","and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secondaryLabel"]}," as secondary context. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," field can be used to"," ","select an icon (street, building, postal code, etc.)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-handle-the-action","__idx":4},"children":["Step 2: Handle the action"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the customer selects a prediction, check its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]},":"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"if-action-is-resolve","__idx":5},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resolve"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The prediction is a specific address. Proceed to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#step-3-resolve-to-full-address"},"children":["Step 3"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"if-action-is-expand","__idx":6},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expand"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The prediction is a container with child addresses. Call search again with the"," ","prediction's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["containerId"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"Request","header":{"title":"Request","controls":{"copy":{}}},"source":"curl -X GET \"https://api.ingrid.com/v1/delivery/address/search?countryCode=GB&containerId=grp_street_882\" \\\n -H \"Authorization: Bearer \"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Response","header":{"title":"Response","controls":{"copy":{}}},"source":"{\n \"predictions\": [\n {\n \"id\": \"addr_gbr_30012001\",\n \"label\": \"Flat 1, 10 Buckingham Street\",\n \"secondaryLabel\": \"London, WC2N 6DF\",\n \"action\": \"resolve\",\n \"type\": \"premise\"\n },\n {\n \"id\": \"addr_gbr_30012002\",\n \"label\": \"Flat 2, 10 Buckingham Street\",\n \"secondaryLabel\": \"London, WC2N 6DF\",\n \"action\": \"resolve\",\n \"type\": \"premise\"\n },\n {\n \"id\": \"addr_gbr_30012003\",\n \"label\": \"Flat 3, 10 Buckingham Street\",\n \"secondaryLabel\": \"London, WC2N 6DF\",\n \"action\": \"resolve\",\n \"type\": \"premise\"\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Display the new predictions. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Expanding can be recursive — a container may contain more containers — but in"," ","practice most lookups resolve within one or two levels."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-resolve-to-full-address","__idx":7},"children":["Step 3: Resolve to full address"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the customer selects a prediction with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action: \"resolve\""]},", call the"," ","details endpoint with its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"Request","header":{"title":"Request","controls":{"copy":{}}},"source":"curl -X GET \"https://api.ingrid.com/v1/delivery/address/details/addr_gbr_10045832\" \\\n -H \"Authorization: Bearer \"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Response","header":{"title":"Response","controls":{"copy":{}}},"source":"{\n \"deliveryAddress\": {\n \"countryCode\": \"GB\",\n \"postalCode\": \"TS10 3JQ\",\n \"addressLines\": [\"10 Buckingham Road\"],\n \"locality\": \"Redcar\"\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-populate-the-form","__idx":8},"children":["Step 4: Populate the form"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Map the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DeliveryAddress"]}," fields to your form inputs. The field names"," ","in the response match the field names from the"," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-form"},"children":["form endpoint"]},", so the mapping is direct."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After populating, allow the customer to review and edit the pre-filled values"," ","before proceeding."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-focus-parameter","__idx":9},"children":["The focus parameter"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"focus value"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["focus"]}," value"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Behavior"},"children":["Behavior"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addressLines"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Search street addresses (default behavior)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postalCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Search by postal code. Useful for postal code lookups (PAF-style)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locality"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Search city or town names"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["administrativeArea"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Search states, provinces, or regions"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"Example: postal code focused search","header":{"title":"Example: postal code focused search","controls":{"copy":{}}},"source":"curl -X GET \"https://api.ingrid.com/v1/delivery/address/search?countryCode=GB&query=SW1A&focus=postalCode\" \\\n -H \"Authorization: Bearer \"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"debouncing-and-performance","__idx":10},"children":["Debouncing and performance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not call search with fewer than 2-3 characters — the results will be too"," ","broad to be useful."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":11},"children":["Error handling"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When it occurs"},"children":["When it occurs"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid or missing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["countryCode"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 Not Found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," passed to the details endpoint does not exist or has expired"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500 Internal Server Error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server-side issue — retry with exponential backoff"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Prediction IDs are opaque and may expire. If a details call returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]},","," ","prompt the customer to search again."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":12},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-validation"},"children":["Address validation"]}," — verify the resolved address"," ","before creating an order"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/country-reference"},"children":["Country reference"]}," — country-specific"," ","addressing rules"]}]}]},"headings":[{"value":"Address autocomplete","id":"address-autocomplete","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Overview","id":"overview","depth":2},{"value":"Step 1: Search for addresses","id":"step-1-search-for-addresses","depth":2},{"value":"Step 2: Handle the action","id":"step-2-handle-the-action","depth":2},{"value":"If action is resolve","id":"if-action-is-resolve","depth":3},{"value":"If action is expand","id":"if-action-is-expand","depth":3},{"value":"Step 3: Resolve to full address","id":"step-3-resolve-to-full-address","depth":2},{"value":"Step 4: Populate the form","id":"step-4-populate-the-form","depth":2},{"value":"The focus parameter","id":"the-focus-parameter","depth":2},{"value":"Debouncing and performance","id":"debouncing-and-performance","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Address Autocomplete","description":"How to add type-ahead address search to your checkout using the expand and resolve pattern","seo":{"title":"Address autocomplete"}},"lastModified":"2026-02-24T19:14:57.409Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-resources/ingrid-api/guides/address-autocomplete","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}