> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cocartapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search for Address Suggestions

> Search for address suggestions using an autocomplete provider during checkout

<Warning>
  This endpoint is currently shown as a preview of what's currently in development and is subject to change.
</Warning>

<Info>
  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.
</Info>

## 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


## OpenAPI

````yaml api-reference/pre-release/openapi-spec-preview.yaml get /address/search
openapi: 3.0.3
info:
  title: CoCart Preview API
  description: >
    CoCart Preview provides enhanced REST API endpoints for WooCommerce headless
    e-commerce solutions.

    This API extends CoCart with additional functionality for checkout, customer
    account management, and order handling.


    ## Authentication


    The API supports multiple authentication methods:

    - **Cart Key**: For guest customers, pass the cart key via `Cart-Key` header
    or `cart_key` parameter

    - **Basic Auth**: For registered customers using username/password

    - **JWT**: For registered customers using JWT tokens (requires JWT plugin)

    - **Session**: For logged-in WordPress users


    ## Base URL


    All API endpoints are prefixed with `/wp-json/cocart/preview/`


    ## Response Format


    All responses follow the CoCart standard format with consistent error
    handling and data structure.
  termsOfService: http://cocartapi.com/terms-of-conditions-polar/
  contact:
    email: support@cocartapi.com
  license:
    name: GNU General Public License v3.0
    url: http://www.gnu.org/licenses/gpl-3.0.html
  version: 0.0.1
servers:
  - url: '{protocol}://{host}/wp-json/cocart/preview'
    description: API Preview
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      host:
        default: example-store.com
        description: Your store domain
security: []
tags:
  - name: Checkout
    description: Complete checkout process including payment and order creation
  - name: My Account
    description: Customer account information and profile management
  - name: My Orders
    description: Customer order history and details
  - name: My Downloads
    description: Customer digital downloads
  - name: My Subscriptions
    description: Customer subscription management
externalDocs:
  description: Find out more about CoCart API
  url: https://docs.cocartapi.com
paths:
  /address/search:
    get:
      tags:
        - Checkout
      summary: Search for address suggestions
      description: >-
        Search for address suggestions using an autocomplete provider during
        checkout
      operationId: searchAddresses
      parameters:
        - name: query
          in: query
          description: Search query string (minimum 3 characters)
          required: true
          schema:
            type: string
            minLength: 3
        - name: country
          in: query
          description: ISO 3166-1 alpha-2 country code to limit search results
          required: false
          schema:
            type: string
            minLength: 2
            maxLength: 2
        - name: type
          in: query
          description: Address type for the search context
          required: false
          schema:
            type: string
            enum:
              - billing
              - shipping
            default: billing
        - name: provider
          in: query
          description: Specific address autocomplete provider ID to use
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Address suggestions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressSearchResponse'
              examples:
                addressSearch:
                  $ref: '#/components/examples/AddressSearchExample'
        '400':
          description: Bad request - invalid query or country not supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error - no provider available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AddressSearchResponse:
      type: object
      properties:
        suggestions:
          type: array
          items:
            $ref: '#/components/schemas/AddressSuggestion'
          description: List of address suggestions
        count:
          type: integer
          description: Total number of suggestions returned
        provider:
          $ref: '#/components/schemas/AddressProvider'
        search_country:
          type: string
          description: Country code used for the search
        query:
          type: string
          description: Original search query
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code identifier
        message:
          type: string
          description: Human-readable error message
        data:
          type: object
          description: Additional error data
          properties:
            status:
              type: integer
              description: HTTP status code
    AddressSuggestion:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the address suggestion
        label:
          type: string
          description: Display label for the address suggestion
        matched_substrings:
          type: array
          items:
            $ref: '#/components/schemas/AddressMatchedSubstring'
          description: Portions of the label that match the query
    AddressProvider:
      type: object
      properties:
        id:
          type: string
          description: Provider identifier
        name:
          type: string
          description: Provider display name
    AddressMatchedSubstring:
      type: object
      properties:
        offset:
          type: integer
          description: Starting position of the matched substring
        length:
          type: integer
          description: Length of the matched substring
  examples:
    AddressSearchExample:
      value:
        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'

````