Working with Addresses

Learn how the Square API model works with address information.

Link to section

Overview

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

Addresses are stored using the free-form data entry fields address_line_1 and address_line_2 so that people can represent their addresses in any way they need. Other address components, such as postal_code, locality (city), and administrative_district_level_1 (state, prefecture, or province) are broken out into their own fields because software sometimes behaves differently based on them. 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.

Most addresses contain each of these fields, but their meanings differ based on the locality. The following table shows details about what each address field represents for each country in which Square operates:

Address fieldUnited StatesCanadaAustraliaUnited KingdomIrelandFranceSpain
address_line_1Address line 1Address line 1Address line 1Address line 1Address line 1Address line 1Address line 1
address_line_2Address line 2Address line 2Address line 2Address line 2Address line 2Address line 2Address line 2
localityCityCitySuburbTownTown/cityCityLocality
administrative_district_level_1StateProvinceState(blank)County(blank)Province
postal_codeZIP codePostal codePostal codePostal codeEircodePostcodePostal 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 Locations API or Customers API to access information about locations or customers, respectively, including their addresses.

Square products (such as Square Point of Sale and the Seller 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.

Link to section

Address examples

Addresses in the Square data model look slightly different depending on the country in which the address is located. The following are example addresses for each country in which Square operates.

Link to section

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" } }
Link to section

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" } }
Link to section

Australia

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

United Kingdom

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

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" } }
Link to section

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" } }
Link to section

Spain

{ "address": { "address_line_1": "Julia Machado García", "address_line_2": "Calle del Ejemplo, 195", "postal_code": "08226", "locality": "TERRASSA", "administrative_district_level_1": "BARCELONA", "country": "ES" } }
Link to section

See also