Getting Started with Placekey.io Part 2

by Placekey

In our previous post, we helped you get started with the Placekey API. Whether it’s establishing the market rate for a property, helping environmentalists study global warming trends in a neighborhood, or getting your food delivered to the right address, matching addresses correctly is crucial in this day and age. Placekey believes that such location data can be combined so as to drive a greater good, unlocking new insights on location data. With this post, you’ll learn how to get a Placekey for single locations, points-of-interest, bulk entries, and more.

‍

Matching Behaviour

In order to properly locate a physical address, the Placekey API’s matching algorithm tries a few different queries sequentially, returning the best match of the first query with a high enough score to feel assured it's a true match. It runs 5 such queries, in this order:

If the address you've sent in is valid, then we search for a POI at that address placekey with a name that exactly case-insensitively matches the location_name you've sent in.
If this does not match (or if the address you sent in wasn't valid) but you've sent in a latitude and longitude with your query, then we search for that location_name and a fuzzy street address within 1km of your coordinates.
If this still does not match but you've sent in a postal code, then we search specifically for a POI in that postal code and look for a location_name match and a fuzzy street address match
If none of the above match and you have sent in a city and a region, then we require a strict match on city/region, a match on POI name, and a fuzzy match on street address.
Finally, if none of the above match, we stop searching for POI and perform an address match.

STRICT NAME MATCH

If strict_name_match is false, all location_name matches after Step 1 are fuzzy. If strict_name_match is true, all location_name matches are exact case-insensitive.

STRICT ADDRESS MATCH

If strict_address_match is false, then address matches are fuzzy across street_address, city, state, and postal_code. If strict_address_match is true, then we reject all matches that do not exactly match the input address fields.

Single Locations

To find the Placekey for a single location, use the /placekey endpoint and specify any complete combination of location information. Below are some examples:

Get a Placekey for a pair of coordinates

Get a Placekey with a query ID of your choice

When you specify a query ID, it is echoed back to you. This can be useful if you have lots of queries in flight and you want to line them back up afterwards.

Get a Placekey for an address

curl --location --request POST 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "query": {
    "street_address": "1543 Mission Street, Floor 3",
    "city": "San Francisco",
    "region": "CA",
    "postal_code": "94105",
    "iso_country_code": "US"
  }
}'

Get a Placekey for an address with strict address matching

curl --location --request POST 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "query": {
        "street_address": "598 Portola Dr",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94131",
        "iso_country_code": "US"
  },
  "options": {
      "strict_address_match": true
  }
}'

Get a Placekey for a POI

You can also get a Placekey for a Point-of-Interest, or any specific physical location that someone may find interesting or is searching for. (Since it’s a mouthful, Point-of-Interest is often abbreviated as 'POI').

Restaurants, retail stores, and grocery stores are all examples of POI.

curl --location --request POST 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": {
        "location_name": "San Francisco City Hall",
        "street_address": "1 Dr Carlton B Goodlett Pl",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94102",
        "iso_country_code": "US"
    }
}'

Get a Placekey for a POI with strict name matching

Strictly matching its name, you can get a Placekey for a POI. If the name does not match, we fall back to address matching behaviour.

curl --location --request POST 'https://api.placekey.io/v1/placekey' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": {
        "location_name": "San Francisco City Hall",
        "street_address": "1 Dr Carlton B Goodlett Pl",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94102",
        "iso_country_code": "US"
    },
    "options": {
        "strict_name_match": true
    }
}'

Bulk API

Beyond single locations and specific names and addresses, if you have a large number of places you want to match, you can send batches of size no more than 100 over at once. We require that all queries in a batch have the same iso_country_code.

Get Placekeys for multiple things at once

With multiple queries, you also have the option to specify an ID with each query that echoes back.

curl --location --request POST 'https://api.placekey.io/v1/placekeys' \
--header 'apikey: {{apikey}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "queries": [
        {
            "street_address": "1543 Mission Street, Floor 3",
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94105",
            "iso_country_code": "US"
        },
        {
            "query_id": "thisqueryidaloneiscustom",
            "location_name": "Twin Peaks Petroleum",
            "street_address": "598 Portola Dr",
            "city": "San Francisco",
            "region": "CA",
            "postal_code": "94131",
            "iso_country_code": "US"
        },
        {
            "latitude": 37.7371,
            "longitude": -122.44283
        }
    ]
}'

A Common Error

An error message of “Parameter query is required” can arise when doing Bulk API. Your request body should be a JSON object that contains the query field within which you specify the query parameters you would like to match on. If the parameter is missing you will not be able to match to a placekey. Read the API description to see how to construct a query or try one of the examples listed above.

Placekey Blog