Skip to main content
GET
/
address
/
search
Error
A valid request URL is required to generate request examples
{
  "suggestions": [
    {
      "id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
      "label": "123 Main Street, Anytown, CA 12345, USA",
      "matched_substrings": [
        {
          "offset": 0,
          "length": 3
        }
      ]
    },
    {
      "id": "ChIJP3Sa8ziYEmsRUKgyFmh9AQM",
      "label": "123 Main Avenue, Anytown, CA 12346, USA",
      "matched_substrings": [
        {
          "offset": 0,
          "length": 3
        }
      ]
    }
  ],
  "count": 2,
  "provider": {
    "id": "google",
    "name": "Google Places"
  },
  "search_country": "US",
  "query": "123"
}
This endpoint is currently shown as a preview of what’s currently in development and is subject to change.
Provider selection is handled automatically server-side based on configuration and country. The API automatically selects the appropriate provider, but you can set the provider field when passed back to the details endpoint.

​
Country Detection Logic

When no country is explicitly provided, the API uses this fallback order:
  1. Explicitly provided country parameter
  2. Customer’s existing billing/shipping address (for logged-in users)
  3. Cart session country (if previously set)
  4. Store’s default base country
  5. ‘US’ as ultimate fallback

Query Parameters

​
query
string
required

Search query string (minimum 3 characters)

Minimum string length: 3
​
country
string

ISO 3166-1 alpha-2 country code to limit search results

Required string length: 2
​
type
enum<string>
default:billing

Address type for the search context

Available options:
billing,
shipping
​
provider
string

Specific address autocomplete provider ID to use

Response

Address suggestions retrieved successfully

​
suggestions
object[]

List of address suggestions

​
count
integer

Total number of suggestions returned

​
provider
object
​
search_country
string

Country code used for the search

​
query
string

Original search query