ListLocations

{
  "type": "object",
  "description": "Defines the fields that are included in the response body of\na request to the __ListLocations__ endpoint.\n\nOne of `errors` or `locations` is present in a given response (never both).",
  "properties": {
    "errors": {
      "type": "array",
      "description": "Any errors that occurred during the request.",
      "items": {
        "type": "object",
        "description": "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information.",
        "required": [
          "category",
          "code"
        ],
        "properties": {
          "category": {
            "type": "string",
            "description": "The high-level category for the error."
          },
          "code": {
            "type": "string",
            "description": "The specific code of the error."
          },
          "detail": {
            "type": "string",
            "description": "A human-readable description of the error for debugging purposes."
          },
          "field": {
            "type": "string",
            "description": "The name of the field provided in the original request (if any) that\nthe error pertains to."
          }
        }
      }
    },
    "locations": {
      "type": "array",
      "description": "The business locations.",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "object",
            "description": "Represents a postal address in a country. The address format is based \non an [open-source library from Google](https://github.com/google/libaddressinput). For more information, \nsee [AddressValidationMetadata](https://github.com/google/libaddressinput/wiki/AddressValidationMetadata). \nThis format has dedicated fields for four address components: postal code, \nlocality (city), administrative district (state, prefecture, or province), and \nsublocality (town or village). These components have dedicated fields in the \n`Address` object because software sometimes behaves differently based on them. \nFor example, sales tax software may charge different amounts of sales tax \nbased on the postal code, and some software is only available in \ncertain states due to compliance reasons.\n\nFor the remaining address components, the `Address` type provides the \n`address_line_1` and `address_line_2` fields for free-form data entry. \nThese fields are free-form because the remaining address components have \ntoo many variations around the world and typical software does not parse \nthese components. These fields enable users to enter anything they want. \n\nNote that, in the current implementation, all other `Address` type fields are blank. \nThese include `address_line_3`, `sublocality_2`, `sublocality_3`, \n`administrative_district_level_2`, `administrative_district_level_3`, \n`first_name`, `last_name`, and `organization`. \n\nWhen it comes to localization, the seller's language preferences \n(see [Language preferences](https://developer.squareup.com/docs/locations-api#location-specific-and-seller-level-language-preferences)) \nare ignored for addresses. Even though Square products (such as Square Point of Sale \nand the Seller Dashboard) mostly use a seller's language preference in \ncommunication, when it comes to addresses, they will use English for a US address, \nJapanese for an address in Japan, and so on.",
            "properties": {
              "address_line_1": {
                "type": "string",
                "description": "The first line of the address.\n\nFields that start with `address_line` provide the address's most specific\ndetails, like street number, street name, and building name. They do *not*\nprovide less specific details like city, state/province, or country (these\ndetails are provided in other fields)."
              },
              "address_line_2": {
                "type": "string",
                "description": "The second line of the address, if any."
              },
              "address_line_3": {
                "type": "string",
                "description": "The third line of the address, if any."
              },
              "administrative_district_level_1": {
                "type": "string",
                "description": "A civil entity within the address's country. In the US, this\nis the state."
              },
              "administrative_district_level_2": {
                "type": "string",
                "description": "A civil entity within the address's `administrative_district_level_1`.\nIn the US, this is the county."
              },
              "administrative_district_level_3": {
                "type": "string",
                "description": "A civil entity within the address's `administrative_district_level_2`,\nif any."
              },
              "country": {
                "type": "string",
                "description": "The address's country, in ISO 3166-1-alpha-2 format."
              },
              "first_name": {
                "type": "string",
                "description": "Optional first name when it's representing recipient."
              },
              "last_name": {
                "type": "string",
                "description": "Optional last name when it's representing recipient."
              },
              "locality": {
                "type": "string",
                "description": "The city or town of the address."
              },
              "organization": {
                "type": "string",
                "description": "Optional organization name when it's representing recipient."
              },
              "postal_code": {
                "type": "string",
                "description": "The address's postal code."
              },
              "sublocality": {
                "type": "string",
                "description": "A civil region within the address's `locality`, if any."
              },
              "sublocality_2": {
                "type": "string",
                "description": "A civil region within the address's `sublocality`, if any."
              },
              "sublocality_3": {
                "type": "string",
                "description": "A civil region within the address's `sublocality_2`, if any."
              }
            }
          },
          "business_email": {
            "type": "string",
            "description": "The email of the location.\nThis email is visible to the customers of the location.\nFor example, the email appears on customer receipts. \nFor example, `help@squareup.com`."
          },
          "business_hours": {
            "type": "object",
            "description": "Represents the hours of operation for a business location.",
            "properties": {
              "periods": {
                "type": "array",
                "description": "The list of time periods during which the business is open. There may be at most 10\nperiods per day.",
                "items": {
                  "type": "object",
                  "description": "Represents a period of time during which a business location is open.",
                  "properties": {
                    "day_of_week": {
                      "type": "string",
                      "description": "The day of week for this time period."
                    },
                    "end_local_time": {
                      "type": "string",
                      "description": "The end time of a business hours period, specified in local time using partial-time\nRFC 3339 format."
                    },
                    "start_local_time": {
                      "type": "string",
                      "description": "The start time of a business hours period, specified in local time using partial-time\nRFC 3339 format."
                    }
                  }
                }
              }
            }
          },
          "business_name": {
            "type": "string",
            "description": "The business name of the location\nThis is the name visible to the customers of the location.\nFor example, this name appears on customer receipts."
          },
          "capabilities": {
            "type": "array",
            "description": "The Square features that are enabled for the location.\nSee [LocationCapability](https://developer.squareup.com/reference/square_2021-08-18/enums/LocationCapability) for possible values.",
            "items": {
              "type": "string"
            }
          },
          "coordinates": {
            "type": "object",
            "description": "Latitude and longitude coordinates.",
            "properties": {
              "latitude": {
                "type": "number",
                "description": "The latitude of the coordinate expressed in degrees."
              },
              "longitude": {
                "type": "number",
                "description": "The longitude of the coordinate expressed in degrees."
              }
            }
          },
          "country": {
            "type": "string",
            "description": "The country of the location, in ISO 3166-1-alpha-2 format.\n\nSee [Country](https://developer.squareup.com/reference/square_2021-08-18/enums/Country) for possible values."
          },
          "created_at": {
            "type": "string",
            "description": "The time when the location was created, in RFC 3339 format.\nFor more information, see [Working with Dates](https://developer.squareup.com/docs/build-basics/working-with-dates)."
          },
          "currency": {
            "type": "string",
            "description": "The currency used for all transactions at this location,\nin ISO 4217 format.\nSee [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values."
          },
          "description": {
            "type": "string",
            "description": "The description of the location."
          },
          "facebook_url": {
            "type": "string",
            "description": "The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. For example, `https://www.facebook.com/square`."
          },
          "full_format_logo_url": {
            "type": "string",
            "description": "The URL of a full-format logo image for the location. The Seller must choose this logo in the\nSeller dashboard (Receipts section) for the logo to appear on transactions (such as receipts, invoices)\nthat Square generates on behalf of the Seller. This image can have an aspect ratio of 2:1 or greater\nand is recommended to be at least 1280x648 pixels."
          },
          "id": {
            "type": "string",
            "description": "The Square-issued ID of the location."
          },
          "instagram_username": {
            "type": "string",
            "description": "The Instagram username of the location without the '@' symbol. For example, `square`."
          },
          "language_code": {
            "type": "string",
            "description": "The language associated with the location, in\n[BCP 47 format](https://tools.ietf.org/html/bcp47#appendix-A). \nFor more information, see [Location language code](https://developer.squareup.com/docs/locations-api#location-language-code)."
          },
          "logo_url": {
            "type": "string",
            "description": "The URL of the logo image for the location. The Seller must choose this logo in the Seller\ndashboard (Receipts section) for the logo to appear on transactions (such as receipts, invoices)\nthat Square generates on behalf of the Seller. This image should have an aspect ratio\nclose to 1:1 and is recommended to be at least 200x200 pixels."
          },
          "mcc": {
            "type": "string",
            "description": "The merchant category code (MCC) of the location, as standardized by ISO 18245.\nThe MCC describes the kind of goods or services sold at the location."
          },
          "merchant_id": {
            "type": "string",
            "description": "The ID of the merchant that owns the location."
          },
          "name": {
            "type": "string",
            "description": "The name of the location.\nThis information appears in the dashboard as the nickname.\nA location name must be unique within a seller account."
          },
          "phone_number": {
            "type": "string",
            "description": "The phone number of the location in human readable format. For example, `+353 80 0 098 8099`."
          },
          "pos_background_url": {
            "type": "string",
            "description": "The URL of the Point of Sale background image for the location."
          },
          "status": {
            "type": "string",
            "description": "The status of the location, either active or inactive."
          },
          "tax_ids": {
            "type": "object",
            "description": "The tax IDs that a Location is operating under.",
            "properties": {
              "eu_vat": {
                "type": "string",
                "description": "The EU VAT number for this location. For example, \"IE3426675K\".\nIf the EU VAT number is present, it is well-formed and has been\nvalidated with VIES, the VAT Information Exchange System."
              },
              "fr_naf": {
                "type": "string",
                "description": "The French government uses the NAF (Nomenclature des Activités Françaises) to display and\ntrack economic statistical data. This is also called the APE (Activite Principale de l’Entreprise) code.\nFor example, 6910Z."
              },
              "fr_siret": {
                "type": "string",
                "description": "The SIRET (Système d'Identification du Répertoire des Entreprises et de leurs Etablissements)\nnumber is a 14 digits code issued by the French INSEE. For example, \"39922799000021\"."
              }
            }
          },
          "timezone": {
            "type": "string",
            "description": "The [IANA Timezone](https://www.iana.org/time-zones) identifier for\nthe timezone of the location."
          },
          "twitter_username": {
            "type": "string",
            "description": "The Twitter username of the location without the '@' symbol. For example, `Square`."
          },
          "type": {
            "type": "string",
            "description": "The type of the location, either physical or mobile."
          },
          "website_url": {
            "type": "string",
            "description": "The website URL of the location.  For example, `https://squareup.com`."
          }
        }
      }
    }
  }
}