Locations API: Cookbook

Search for Locations

Create helper functions to search for account locations according to the provided filter criteria.

Locations API

Before you start

  • You will need an access token. If you are using OAuth, you will need the MERCHANT_PROFILE_READ permission.
  • You need to have registered an application in the Application Dashboard and configured your web application with the associated Application ID.

Step 1: Create comparison helper functions

  1. Create an Address comparison function that returns true if the filter criteria set in filter matches the properties in target.
function filterAddress($filter, $target) {

  // If we're filtering on the address and the target is null, it should be
  // excluded according to the filter criteria. Otherwise it should pass.
  if (is_null($target) && is_null($filter)) { return true ; }
  elseif (is_null($filter)) { return true ; }
  elseif (is_null($target)) { return false ; }

  $match =
    (is_null($filter->getAddressLine1()) ? true :
    strcasecmp($filter->getAddressLine1(), $target->getAddressLine1()) === 0)
    &&
    (is_null($filter->getAddressLine2()) ? true :
    strcasecmp($filter->getAddressLine2(), $target->getAddressLine2()) === 0)
    &&
    (is_null($filter->getAddressLine3()) ? true :
    strcasecmp($filter->getAddressLine3(), $target->getAddressLine3()) === 0)
    &&
    (is_null($filter->getLocality()) ? true :
    strcasecmp($filter->getLocality(), $target->getLocality()) === 0)
    &&
    (is_null($filter->getSublocality()) ? true :
    strcasecmp($filter->getSublocality(), $target->getSublocality()) === 0)
    &&
    (is_null($filter->getSublocality2()) ? true :
    strcasecmp($filter->getSublocality2(), $target->getSublocality2()) === 0)
    &&
    (is_null($filter->getSublocality3()) ? true :
    strcasecmp($filter->getSublocality3(), $target->getSublocality3()) === 0)
    &&
    (is_null($filter->getAdministrativeDistrictLevel1()) ? true :
      strcasecmp(
        $filter->getAdministrativeDistrictLevel1(),
        $target->getAdministrativeDistrictLevel1()
      ) === 0)
    &&
    (is_null($filter->getAdministrativeDistrictLevel2()) ? true :
      strcasecmp(
        $filter->getAdministrativeDistrictLevel2(),
        $target->getAdministrativeDistrictLevel2()
      ) === 0)
    &&
    (is_null($filter->getAdministrativeDistrictLevel3()) ? true :
      strcasecmp(
        $filter->getAdministrativeDistrictLevel3(),
        $target->getAdministrativeDistrictLevel3()
      ) === 0)
    &&
    (is_null($filter->getPostalCode()) ? true :
    strcasecmp($filter->getPostalCode(), $target->getPostalCode()) === 0)
    &&
    (is_null($filter->getCountry()) ? true :
    strcasecmp($filter->getCountry(), $target->getCountry()) === 0)
    &&
    (is_null($filter->getFirstName()) ? true :
    strcasecmp($filter->getFirstName(), $target->getFirstName()) === 0)
    &&
    (is_null($filter->getLastName()) ? true :
    strcasecmp($filter->getLastName(), $target->getLastName()) === 0)
    &&
    (is_null($filter->getOrganization()) ? true :
    strcasecmp($filter->getOrganization(), $target->getOrganization()) === 0)
    ;
}
  1. Create a Location comparison function that returns true if the filter criteria set in filter matches the properties in target.
function filterLocation($filter, $target){

  // If we're filtering on a location and the target is null, it should be
  // excluded according to the filter criteria. Otherwise it should pass when
  // the filter is null.
  if (is_null($target) && is_null($filter)) { return true ; }
  elseif (is_null($filter)) { return true ; }
  elseif (is_null($target)) { return false ; }

  $match =
    (is_null($filter->getId()) ? true :
    strcasecmp($filter->getId(), $target->getId()) === 0)
    &&
    (is_null($filter->getName()) ? true :
    strcasecmp($filter->getName(), $target->getName()) === 0)
    &&
    (is_null($filter->getTimezone()) ? true :
    strcasecmp($filter->getName(), $target->getName()) === 0)
    &&
    (is_null($filter->getStatus()) ? true :
    strcasecmp($filter->getStatus(), $target->getStatus()) === 0)
    &&
    (is_null($filter->getCreatedAt()) ? true :
    strcasecmp($filter->getCreatedAt(), $target->getCreatedAt()) === 0)
    &&
    (is_null($filter->getMerchantId()) ? true :
    strcasecmp($filter->getMerchantId(), $target->getMerchantId()) === 0)
    &&
    (is_null($filter->getCountry()) ? true :
    strcasecmp($filter->getCountry(), $target->getCountry()) === 0)
    &&
    (is_null($filter->getLanguageCode()) ? true :
    strcasecmp($filter->getLanguageCode(), $target->getLanguageCode()) === 0)
    &&
    (is_null($filter->getCurrency()) ? true :
    strcasecmp($filter->getCurrency(), $target->getCurrency()) === 0)
    &&
    (is_null($filter->getPhoneNumber()) ? true :
    strcasecmp($filter->getPhoneNumber(), $target->getPhoneNumber()) === 0)
    &&
    (is_null($filter->getType()) ? true :
    strcasecmp($filter->getType(), $target->getType()) === 0)
    &&
    (is_null($filter->getWebsiteUrl()) ? true :
    strcasecmp($filter->getWebsiteUrl(), $target->getWebsiteUrl()) === 0)
    ;

    // Capabilities is an array. We consider it a match as long as all the
    // capabilities in the filter exist in the list of capabilities in the target
    if ($match) {
      if (is_null($target->getCapabilities()) && is_null($filter->getCapabilities())) {
        $match = true ;
      }
      elseif (is_null($filter->getCapabilities())) { $match = true ; }
      elseif (is_null($target->getCapabilities())) { $match = false ; }
      else {
        foreach ($filter->getCapabilities() as $value) {
          $match = $match && in_array($value, $target->getCapabilities());
        }
      }
    }

    $match = $match && filterAddress($filter->getAddress(), $target->getAddress());

  return $match;
}

Step 2: Create a helper function to find a specific location

The functions below accepts an access token and an optional Location object whose properties are matched against the account locations to find a match. By default, the function will look for the first location that is active and has credit card payments enabled. If a valid location cannot be found, the function returns null.

function getLocation($accessToken, $filter=null) {

  $returnLocation = null ;

  // Get the default Connect v2 API client configuration
  // (no access token set) and construct a locations api client
  $apiConfiguration = new \SquareConnect\Configuration();
  $apiConfiguration->setAccessToken($accessToken);
  $apiClient = new \SquareConnect\ApiClient($apiConfiguration);
  $locationsApi = new \SquareConnect\Api\LocationsApi($apiClient);

  // Call ListLocations
  try {
    $locations = $locationsApi->listLocations();
  } catch (\SquareConnect\ApiException $e) {
    // Display the exception details and forward the exception
    echo printError("LocationApi", "listLocations", $e);
    throw $e;
  }

  // Use the default search criteria
  if (is_null($filter)) {
    $filter = new SquareConnect\model\Location;
    $filter->setStatus("ACTIVE");
    $filter->setCapabilities(array("CREDIT_CARD_PROCESSING"));
  }

  // Look through the list of locations for one that matches the filter
  foreach ($locations->getLocations() as $currLocation) {
      if (filterLocation($filter, $currLocation)) {
        $returnLocation = $currLocation;
        break;
      }
  }

  return $returnLocation;
}

Step 3: Call the helper function to load a location

  1. Create a local Location instance and set only the property values you want to filter against:
$filter = new SquareConnect\model\Location();

$filterAddress = new SquareConnect\model\Address();
$filterAddress->setAddressLine1('123 Main Street');

$filter->setAddress($filterAddress);
$filter->setName("SF Store");
$filter->setStatus("ACTIVE");
$filter->setCapabilities(array("CREDIT_CARD_PROCESSING"));

  1. Call the helper function with a valid access token and the filter. The code below uses the getAccessToken helper function in the config file template from Github.
$accessToken = getAccessToken();
$location = getLocation($accessToken, $filter);

Contact Developer Support, join our Slack channel, or ask for help on Stack Overflow