Working with Addresses

Learn how the Square API model works with address information.

Overview

The address format used by Square is based on an open-source library from Google. For more information, see AddressValidationMetadata.

Square APIs store addresses in an Address object. The free-form address_line_1 and address_line_2 fields provide a flexible format for entering the street address with secondary information like apartment, suite, or unit number. Other address components (such as locality, administrative_district_level_1, and postal_code) are separate fields, which allows application logic to be based on their specific values. For example, sales tax software might charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons.

The following table shows what commonly used address fields represent for each country where Square operates:

Address field	Australia	Canada	France	Ireland	Japan	Spain	United Kingdom	United States
`address_line_1`	All countries - free-form street address
`address_line_2`	All countries - free-form street address
`locality`	Suburb	City	City	Town/city	City/ward	Locality	Town	City
`administrative_district_level_1`	State	Province	n/a	County	Prefecture	Province	n/a	State
`postal_code`	Postal code	Postal code	Postcode	Eircode	Postal code	Postal code	Postal code	ZIP code

Note

An Address is stored as a subtype of the object containing it, such as a Location or Customer. Addresses aren't stored independently of these objects. Use the relevant API, such as the Locations API or Customers API, to access the address information stored on these objects.

Square products (such as Square Point of Sale and the Square Dashboard) mostly use a seller's language preference for communication. However, when it comes to addresses, the language preference is overridden. Square products use English for a US address, French for an address in France, and so on.

Address validation

Square validates addresses stored in Location objects. For an address to be valid, it must meet the following requirements:

Address lines can only contain:
- Letters (including Japanese characters)
- Numbers
- Standard punctuation
- Spaces
Address lines cannot contain:
- Control characters
- Emojis
- Special symbols
Address lines must include at least one alphanumeric character. They cannot consist solely of punctuation or spaces.

Address examples

Addresses in the Square data model vary slightly based on the country. The following are example addresses for each country in which Square operates.

Australia

{
  "address": {
    "address_line_1": "300 Main Street",
    "locality": "Melbourne",
    "administrative_district_level_1": "VIC",
    "postal_code": "3000",
    "country": "AU"
  }
}

Canada

{
  "address": {
    "address_line_1": "520 Maple Street",
    "address_line_2": "Floor 2",
    "locality": "Toronto",
    "administrative_district_level_1": "Ontario",
    "postal_code": "M6K1L5",
    "country": "CA"
  }
}

France

{
  "address": {
    "address_line_1": "Chez Mireille COPEAU Apartment 3",
    "address_line_2": "Entrée A Bâtiment Jonquille",
    "postal_code": "33380 MIOS",
    "locality": "CAUDOS",
    "country": "FR"
  }
}

Ireland

{
  "address": {
    "address_line_1": "43 Main Street",
    "address_line_2": "The Liberties",
    "locality": "Dublin 20",
    "administrative_district_level_1": "Co. Dublin",
    "postal_code": "D08XK58",
    "country": "IE"
  }
}

Japan

{
  "address": {
    "address_line_1": "東京都新宿区西新宿1-2-3",
    "address_line_2": "新宿セントラルパークタワー",
    "locality": "新宿区",
    "administrative_district_level_1": "東京都",
    "postal_code": "160-0023",
    "country": "JP"
  }
}

Spain

{
  "address": {
    "address_line_1": "Calle del Ejemplo, 195",
    "address_line_2": "Piso 2, Puerta 3",
    "postal_code": "08226",
    "locality": "TERRASSA",
    "administrative_district_level_1": "BARCELONA",
    "country": "ES"
  }
}

United Kingdom

{
  "address": {
    "address_line_1": "9 Main Street",
    "address_line_2": "Level 4",
    "locality": "London",
    "postal_code": "W1A3AE",
    "country": "GB"
  }
}

United States

{
  "address": {
    "address_line_1": "1955 Broadway",
    "address_line_2": "Suite 600",
    "locality": "Oakland",
    "administrative_district_level_1": "CA",
    "postal_code": "94612",
    "country": "US"
  }
}

Docs