Introduction

The SinglePlatform Matching API enables you to match your own list of businesses against locations in the SinglePlatform database. It takes the list of your business locations, performs the matching according to the matching criteria you specify, and returns the matching results along with other optional information. 

Matching is currently limited to US-based businesses.

*Please note that this Matching API is currently in beta. In the coming weeks, SinglePlatform will be adding additional functionality. We highly encourage feedback from our partners; please do not hesitate to reach out with suggestions or issues.

Partner Agreement Considerations

Our partners are required to comply with SinglePlatform's partner agreement.

Authentication

A valid client ID is required as a URL parameter (client=<your_client_id>) to authenticate and authorize you to use the API.

The Request

URL: http://matching-api.singleplatform.com/location-match

The Matching API server expects HTTP POST requests and no data should be specified in the URL.

POSTs to the Matching API require the following header: Content-Type: application/json

Each POST request should include a JSON-formatted request body with the following keys:

matching_criteria: String, optional [default='NAME_ADDRESS']

Determines what criteria to use when matching your businesses against the SinglePlatform database of locations.

  • Each location is expected to include the key elements according to the chosen matching criteria.
  • There are five options for matching criteria:

    • NAME_ADDRESS:

      • Fuzzy matching is run on a combination of the ‘Name’ and ‘Address’ fields
      • Required fields: 'name', 'address'
      • The following combinations are considered valid addresses:

        • Street address + City + State + Zip
        • Street address + Zip
        • Street address + City + State
      • Format requirements: The address fields can be separated by spaces or commas

    • NAME_GEOLOCATION: 

      • Fuzzy matching is run on a combination of the ‘Name’ and ‘Geolocation’ fields (i.e., Latitude & Longitude values)
      • Required fields: 'name', 'latitude', 'longitude'
    • NAME_PHONE: 

      • An exact match must be found on the ‘phone number’ value and then a fuzzy match is performed on the ‘Name’ value.
      • Required fields: 'name', 'phone'
      • Format requirements: The phone number must be 10 digits. If any additional characters are included (e.g., parentheses), they will be stripped
    • FOURSQUARE_ID: 

      • An exact match must be found on the ‘foursquare_id’ value. 
      • Note that SinglePlatform does not currently have complete coverage of valid Foursquare IDs currently. If you do not receive a match on Foursquare ID, we suggest matching again with different criteria.
      • Required field: 'foursquare_id’
      • You can specify multiple matching criteria for your businesses, e.g. “matching_criteria= NAME_ADDRESS,FOURSQUARE_ID”. The API will try to match your businesses using the first criterion you specify, then do a second round of matching using the second criterion you specify for the businesses that cannot be matched, and so on and so forth.

locations: list of JSON arrays, required

This is the list of locations that you wish to match.

  • Fields passed with a location to the Matching API must conform to the Matching API criteria. Locations with missing fields will not be skipped, a 400 error will be returned instead.

  • If matching by “NAME_ADDRESS” (see “matching_criteria”), the number of locations cannot exceed 100 for each request, and locations with addresses that cannot be normalized will be skipped from matching.

multiple_matches: Boolean, optional [default=False]

Determines if returning multiple matches for one location.

  • If True, up to 5 matches are returned for each location, and will be returned in order of confidence in the match. 
  • If False, will return the best match above the cutoff_threshold (see below). 

cutoff_threshold: Integer [0,100], optional [default=75]

Determines the accuracy threshold of the fuzzy matching.

  • When a single best match is returned, it will include a key called match_accuracy, which specifies the accuracy of the match.

geo_radius: Float, optional [default=0.001]

Determines the radius around the given geo location pair (lat/long). To be used with the NAME_GEOLOCATION matching option. 

The Response

After the API receives a properly formatted request, it attempts to match every location. The response is a JSON object with a single key “response”. 

The response key will contain either a list of matching results or error information (error_code and error_message).

If there is no error and a list of matching results is returned, each result will contain the ‘spv2id’, which is the unique location ID used in SinglePlatform’s database. If one single match is found, the value will be the corresponding ID; if multiple matches are found, the value will be the IDs (comma-separated) of the matches, in descending order of the accuracy; if no match is found, the value will be False.

Examples

Send HTTP POST requests to URL http://matching-api.singleplatform.com/location-match?client=<your_client_id> with the following request bodies.

  1. Matching by NAME_ADDRESS:
{
   "matching_criteria" : "NAME_ADDRESS",
   "locations" : [
      {
         "name" : "Dairy Queen",
         "address" : "2047 US Highway 45 Byp S Trenton TN 38382"
      },
      {
         "address" : "1125 W Riverdale Road Riverdale Utah",
         "name" : "Applebees Neighborhood Grill"
      },
      {
         "name" : "Tomales Bay Oyster Company",
         "address" : "15479 Hwy. One Marshall California"
      },
      {
         "address" : "1825 Washington Rd, Washington PA 15301",
         "name" : "Primo"
      }
   ]
}

Response:

{
   "response" : [
      {
         "normalized_address" : "2047 US Highway 45 Byp S  Trenton TN 38382",
         "address" : "2047 US Highway 45 Byp S Trenton TN 38382",
         "name" : "Dairy Queen",
         "match_accuracy" : 100,
         "spv2id" : "dairy-queen-4584"
      },
      {
         "normalized_address" : "1125 W Riverdale Rd  Riverdale UT 84405",
         "address" : "1125 W Riverdale Road Riverdale Utah",
         "spv2id" : "applebees-1846",
         "name" : "Applebees Neighborhood Grill",
         "match_accuracy" : 81
      },
      {
         "spv2id" : false,
         "name" : "Tomales Bay Oyster Company",
         "address" : "15479 Hwy. One Marshall California"
      },
      {
         "address" : "1825 Washington Rd, Washington PA 15301",
         "normalized_address" : "1825 Washington Rd  Washington PA 15301",
         "match_accuracy" : 100,
         "name" : "Primo",
         "spv2id" : "primo-restaurant"
      }
   ]
}
  1. Matching by NAME_GEOLOCATION:
{
   "matching_criteria" : "NAME_GEOLOCATION",
   "geo_radius" : "0.01",
   "locations" : [
      {
         "name" : "King Cove Chinese Restaurant",
         "longitude" : -162.30706,
         "latitude" : 55.06116
      },
      {
         "name" : "Pomodoro",
         "latitude" : 21.93465,
         "longitude" : -159.52655
      }
   ]
}

Response:

{
   "response" : [
      {
         "spv2id" : false,
         "name" : "King Cove Chinese Restaurant",
         "latitude" : 55.06116,
         "longitude" : -162.30706
      },
      {
         "spv2id" : "pomodoro-39",
         "match_accuracy" : 100,
         "latitude" : 21.93465,
         "name" : "Pomodoro",
         "longitude" : -159.52655
      }
   ]
}
  1. Matching by NAME_PHONE:
{
   "matching_criteria" : "NAME_PHONE",
   "locations" : [
      {
         "name" : "Chen Test Restaurant",
         "phone" : "212-215-0212"
      },
      {
         "name" : "Pomodoro",
         "phone" : "561.496.3503"
      }
   ]
}

Response:

{
   "response" : [
      {
         "name" : "Chen Test Restaurant",
         "phone" : "212-215-0212",
         "spv2id" : false
      },
      {
         "spv2id" : "pomodoro-72",
         "phone" : "561.496.3503",
         "name" : "Pomodoro",
         "match_accuracy" : 100
      }
   ]
}
  1. Matching by FOURSQUARE_ID:
{
   "locations" : [
      {
         "foursquare_id" : "3fd66200f964a52000ea1ee3"
      },
      {
         "name" : "Pomodoro",
         "foursquare_id" : "3fd66200f964a52000ec1ee3"
      }
   ],
   "matching_criteria" : "FOURSQUARE_ID"
}

Response:

{
   "response" : [
      {
         "foursquare_id" : "3fd66200f964a52000ea1ee3",
         "spv2id" : "images-219"
      },
      {
         "spv2id" : false,
         "foursquare_id" : "3fd66200f964a52000ec1ee3"
      }
   ]
}
  1. Matching by NAME_ADDRESS & NAME_PHONE:
{
   "locations" : [
      {
         "name" : "Dairy Queen",
         "address" : "2047 US Highway 45 Byp S Trenton TN 38382"
      },
      {
         "address" : "1825 Washington Rd, Washington PA 15301",
         "name" : "Primo"
      },
      {
         "address" : "17 battery pl",
         "name" : "chenstest"
      },
      {
         "phone" : "561.496.3503",
         "name" : "Pomodoro"
      }
   ],
   "matching_criteria" : "NAME_ADDRESS,NAME_PHONE"
}

Response:

{
   "response" : [
      {
         "match_accuracy" : 100,
         "address" : "2047 US Highway 45 Byp S Trenton TN 38382",
         "name" : "Dairy Queen",
         "spv2id" : "dairy-queen-4584",
         "normalized_address" : "2047 US Highway 45 Byp S  Trenton TN 38382"
      },
      {
         "normalized_address" : "1825 Washington Rd  Washington PA 15301",
         "spv2id" : "primo-restaurant",
         "name" : "Primo",
         "match_accuracy" : 100,
         "address" : "1825 Washington Rd, Washington PA 15301"
      },
      {
         "address" : "17 battery pl",
         "name" : "chenstest",
         "spv2id" : false
      },
      {
         "phone" : "561.496.3503",
         "name" : "Pomodoro",
         "spv2id" : "pomodoro-72",
         "match_accuracy" : 100
      }
   ]
}
  1. Matching by NAME_GEOLOCATION & FOURSQUARE_ID:
{
   "matching_criteria" : "NAME_GEOLOCATION,FOURSQUARE_ID",
   "locations" : [
      {
         "foursquare_id" : "3fd66200f964a52000ea1ee3"
      },
      {
         "name" : "Pomodoro",
         "foursquare_id" : "3fd66200f964a52000ec1ee3"
      },
      {
         "name" : "King Cove Chinese Restaurant",
         "latitude" : 55.06116,
         "longitude" : -162.30706
      },
      {
         "name" : "Pomodoro",
         "longitude" : -159.52655,
         "latitude" : 21.93465
      }
   ]
}

Response:

{
   "response" : [
      {
         "name" : "King Cove Chinese Restaurant",
         "longitude" : -162.30706,
         "spv2id" : false,
         "latitude" : 55.06116
      },
      {
         "longitude" : -159.52655,
         "latitude" : 21.93465,
         "spv2id" : "pomodoro-39",
         "name" : "Pomodoro",
         "match_accuracy" : 100
      },
      {
         "spv2id" : "images-219",
         "foursquare_id" : "3fd66200f964a52000ea1ee3"
      },
      {
         "foursquare_id" : "3fd66200f964a52000ec1ee3",
         "spv2id" : false
      }
   ]
}
  1. Mal-formatted JSON Requests:
{
  "locations"=[
    {
      "foursquare_id":"3fd66200f964a52000ea1ee3"
    }
  ],
  "matching_criteria":"FOURSQUARE_ID"
}

Response:

{
   "response" : {
      "error_message" : "Mal-formatted JSON request body.",
      "error_code" : "INVALID_JSON"
   }
}