1. Addresses
  2. Address Autocomplete

Addresses

Address Autocomplete

The Address Autocomplete API provides address completions, processing standard addresses through Google Maps Places API.

Region is an optional parameter that can be used to filter the results to a specific country. The region parameter is a two-letter country code that can be used to filter the results to a specific country. If the region parameter is not provided, the API will return results from all countries.

Request

POST
`/v1/address/autocomplete`
js 
        const data = {
  address: "1267 Frst Ave",    // Required: The partial address string
  region: "US"               // Optional: Two-letter country code
};

fetch(`https://api.packagex.io/v1/address/autocomplete`, {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
}).then((res) => res.json());

Parameters

  1. address string (Required)
  • The partial address text to be completed.
  • Input is automatically sanitized to remove line breaks.
  1. region string (Optional)
  • Two-letter country code to filter results (e.g., "US", "CA")
  • For US region, it includes territories (PR, VI, GU, MP)
  • When omitted, returns worldwide results.

Response

The API returns up to five most relevant autocompletions in a structured format:

js 
        {
  "message": "5 predictions returned",
  "data": [
    {
      "address": "1267 Forest Avenue, Staten Island, NY, USA",
      "matched_text": "1267 Forest Avenue",
      "autocomplete_text": "Staten Island, NY, USA",
      "description": null
    },
    {
      "address": "1267 Forest Avenue, Highland Park, IL, USA",
      "matched_text": "1267 Forest Avenue",
      "autocomplete_text": "Highland Park, IL, USA",
      "description": null
    },
    {
      "address": "1267 Forest Avenue, Portland, ME, USA",
      "matched_text": "1267 Forest Avenue",
      "autocomplete_text": "Portland, ME, USA",
      "description": null
    },
    {
      "address": "1267 Forest Avenue, Henrico, VA, USA",
      "matched_text": "1267 Forest Avenue",
      "autocomplete_text": "Henrico, VA, USA",
      "description": null
    },
    {
      "address": "1267 Forest Avenue, Pacific Grove, CA, USA",
      "matched_text": "1267 Forest Avenue",
      "autocomplete_text": "Pacific Grove, CA, USA",
      "description": null
    }
  ],
  "status": 200,
  "errors": [],
  "code": null,
  "pagination": null,
  "endpoint": null
}

Response Fields

  • address string: Complete formatted address
  • matched_text string: The portion of the address that matched the input
  • autocomplete_text string: The suggested completion text
  • description string|null: Additional context about the address

Usage

When implementing address autocomplete functionality on the frontend, it is essential to incorporate a debouncing mechanism to manage request frequency. This approach ensures that API requests are dispatched at appropriate intervals, thereby mitigating the risk of exceeding account rate limitations.

INFO

Many addresses contain supplementary information such as unit numbers, suite designations, or floor identifiers that are not returned through the autocomplete API. When creating shipments or contacts, etc., our address API endpoints provide a dedicated field called address_line2 to accommodate this secondary address information. Consequently, it is advisable to incorporate an additional input field in your form specifically designed to capture this supplementary address data.

After receiving data from the address autocompletion endpoint, users typically forward this data along with the address_line2 property to the address parsing API, which then returns the complete PackageX address model for further processing.

Previous <- Model
Next Parse ->