Using Placekey to join events data and POI data

Placekey is a free, universal standard identifier for any physical place, which enables the data pertaining to those places to be easily shared across organizations. PredictHQ provides Placekeys for events data to allow organizations to join our events data to other datasets that use Placekeys. See the Placekey website for more information.

A common use of Placekey and events data is to provide additional information about the Point of Interest (POI) where the event took place. POI data provides detailed information about a location such as address, latitude/longitude, and open hours, and can also be enriched with data including spend data to reveal what’s happening at a location. The combination of events and POI data helps clarify exactly what is driving demand at a location. For example, combining events data with spend data to identify what is driving a spike in spend at a particular location.

Placekey is attached to PredictHQ events records that happen at a particular location. The PredictHQ pipeline looks at the address and other location information like latitude and longitude and attaches the appropriate Placekey based on these values. An example of a Placekey is 222-22t@5yv-j89-g6k. This is for the following address “The Mirage Theatre, 3400 Las Vegas Boulevard South, Las Vegas, NV 89109”. Events that happen at the Mirage Theatre will have this Placekey value.

alt — Image of Placekey with hexes on a map

The format of the Placekey is What@Where. Take the above example: 222-22t@5yv-j89-g6k. For the What component, the first three characters refer to the Address Encoding and the second set of three characters refers to the POI Encoding. The Where part, on the other hand, is made up of three unique character sequences, built upon Uber’s open-source H3 grid system. See the Placekey site for an excellent description of what Placekey is and how it works.

The reason Placekey is useful for joining datasets is because of the general lack of standardization in POI and address data. Addresses are often formatted in different ways. Connecting data by address is difficult, and often inaccurate, and different companies may have different definitions of the latitude, longitude, and area of a location. Using Placekey provides a standard way of representing POI data and makes it easy to join event data with other data sets that also use Placekey.

PredictHQ also partners with SafeGraph. Placekey allows you to join events data and SafeGraph data including SafeGraph Places (POI), SafeGraph Geometry, and SafeGraph Spend.

An overview of Placekey integration with events

Placekey is attached to PredictHQ event records. It is returned in the response from the events API. Placekey is also returned via other integrations like Snowflake and ADX.

Below is an example of the response from the Public API showing the Placekey for an event happening in Las Vegas:

       {
            "relevance": 0.0,
            "id": "FKmCVGdpGMxwcFDF36",
…
                    "type": "venue",
                    "formatted_address": "3400 Las Vegas Boulevard South\nLas Vegas, NV 89109\nUnited States of America"
…
            "geo": {
…
                "placekey": "222-22t@5yv-j89-g6k"
            },

Filtering and searching events with Placekey on the events API

We also have a filter in the events API to allow you to search on Placekey. The filter is called Placekey.

Below is an example of calling the events API with the Placekey filter to get back events that have that specific Placekey.

curl --location --request GET 'https://api.predicthq.com/v1/events?placekey=222-22t@5yv-j89-g6k' \
--header 'Authorization: Bearer <TOKEN> '

You can do the following with the Placekey filter:

Match on an entire Placekey to see all events at that specific location. This can be useful when you want to search for events at a venue. E.g. placekey=222-22t@5yv-j89-g6k
Match address without POI name – This is a query for only an address (the first three digits in the What part along with the Where part); not the POI name. E.g. https://api.predicthq.com/v1/events?placekey=222@5yv-j89-g6k
Match on the full @Where part of Placekey to find events nearby. This returns events where the “@Where” part of Placekey matches but the What part may be different. This will return events within the H3 level 10 hex used by Placekey, which covers approximately a 63-meter radius around the location (see the Placekey whitepaper for more on H3 hexes). E.g. https://api.predicthq.com/v1/events?placekey=@5yv-j89-g6k
Or perform a partial match on the @Where part of Placekey to find nearby events within a larger area. By a partial match we mean instead of including the entire 9 characters of the @Where part of Placekey you can match on 5 or more characters to include a large area. See joining POI and non-POI datasets. E.g. match the first 7 characters: https://api.predicthq.com/v1/events?placekey=@5yv-j89-g

You can find documentation on the events API and the Placekey filter in our API reference documentation. Placekey in Snowflake and ADX

If you are using Snowflake integration, Placekey is returned as the Placekey column in the Snowflake events data. For the Amazon AWS Data Exchange (ADX) data, you will have the Placekey field for events.

If you are using Placekey in Snowflake or another relational database you can perform a join on Placekey between a table with events data and a table with POI data with Placekey (or any other data with a Placekey).

Placekey support for PredictHQ event categories

Our 7 attended event categories support Placekey. The supported categories are concerts, community, conferences, expos, festivals, performing arts, and sports.

Placekey has address support for the United States, United Kingdom, and Canada (see supported countries). For these countries, PredictHQ events will have both the What@Where part where the events have sufficient address information. Some events that don’t have address information may just have the @Where part of Placekey.

Placekey is supported on attended events from 2020 onwards.

For all other countries where Placekey does not support addresses, these events will have the @Where part of Placekey. For example, the Stade Toulousain vs Perpignan event in Toulouse, France has a Placekey of @7f7-mcy-ndv. This is very useful and can also be used to find nearby events and to join with POI data.

See below for the hexagon area covered by @7f7-mcy-ndv:

Note that attended events that have a polygon representing an area do not currently use Placekey. For example marathons, parades and festivals have a geojson polygon representing the area impacted by the event. Placekeys are best suited for events that occur at a specific location rather than events that cover a broad area. See our guide to using polygons events data to find polygons events around a location.

How to use Placekey with events data

Find events at a venue or location

Match on the exact Placekey to find all events at a specific venue. For example, if you want to find all events happening at the Las Vegas Convention Center venue located at 222-224@5yv-j8d-3qz. This query gives you all events happening at this specific venue but not nearby events.

curl --location --request GET 'https://api.predicthq.com/v1/events?placekey=222-224@5yv-j8d-3qz' \
--header 'Authorization: Bearer <token>'

alt — Placekey example for the Las Vegas Convention Center

Find events near a location

Often, events nearby a location can have an impact on your demand. The distance from your location will depend on the type of business—for example, people may travel further to an event when staying in a hotel versus how far people may travel from an event to a restaurant— and the nature of the location also matters (e.g. urban or more rural). To find events nearby a location match on the @Where part of Placekey.

To find events very close to a location, match the full 9 characters of the @Where part of the Placekey that will find events very close to that location. Matching on the full @Where part of Placekey is like finding events within a 63-meter radius. In fact, it’s a hexagon with an edge length of 66 meters on average but it’s similar to drawing a circle with a 63-meter radius.

To find events that are further away match the first x characters of @Where from left to right. So, matching on the full 9 characters is similar to a 63-meter radius, matching on the first 8 characters of the @Where part gives a maximal distance of 443 meters, matching on the first 7 characters encompasses a larger distance, and so on.

See the Placekey documentation on “The structure of a Placekey”. The table with the “Length of shared prefix” and the “Maximal distance (meters)” gives you the approximate size of the H3 hex you get when you match the first X characters of the @Where part of Placekey. The minimum number of characters you can use when matching on the @Where part is 5. See also Joining POI and non-POI datasets with Placekey. See the image below where you can see smaller hexes encompassed in larger hexes

alt — Image showing smaller hexes within larger hexes

Typically for looking at events around a location, we'd recommend looking at the first 6 to 9 characters of Placekey, depending on how large of an area you want to look at.

If using Snowflake or a database, then perform a partial match on the @Where part of Placekey between events and POI data using the first x characters as per the guidance above.

For example, the query below looks at events around 40 W 23rd St, New York, NY 10010 using the first 7 characters of the @Where part of Placekey:

curl --location --request GET 'https://api.predicthq.com/v1/events?placekey=@627-s8h-v' \
--header 'Authorization: Bearer <token> '

One thing to be aware of is that nearby hexagons may have codes that are not very similar. This occurs when Placekey grid cells are near the edges of larger (i.e., lower resolution) hexagons in H3’s spatial hierarchy. This can mean that sometimes using the first x characters of a Placekey will not result in getting all nearby events.

To account for all events around a radius, see “All neighboring hexes'' in the Joining POI tutorial. Or you could convert Placekeys to a latitude and longitude and use a radius query to find nearby events with the within parameter on the events API. Use Placekey_to_geo in the Placekey Python library to convert a Placekey to latitude and longitude.

Find events near a location in Snowflake

PredictHQ’s Events data shared through Snowflake Secure Data Sharing includes Placekey, as a separate column, reflecting the physical location where the event is held. There are a few approaches you could take to use this column when it comes to joining your dataset in Snowflake.

You can simply join PredictHQ’s event tables with your data on the entire Placekey column. This makes sense if your POI data consists of venues where events can be held. If you want to find events happening near the location of your POI locations, you need to join your data with PredictHQ’s Event tables on a substring of the @where part of the Placekey column.

The example below joins a sample PredictHQ Event table on Snowflake that includes Placekey information as a column with SafeGraph “Global Places Sample” POI data (see SafeGraph data examples). In this example, we are trying to perform an Inner Join between the restaurant in the SafeGraph table AND the PredictHQ Events happening nearby. We would only be using the first 7 characters (excluding the hyphens) of the @Where part of the Placekey column for this Inner Join. This results in all possible matches between the restaurants and PredictHQ Events nearby them.

This query should be repurposed with minimal change to be used in other relational data warehouses other than Snowflake.

-- Selecting from PredictHQ’s New York Sample Attended Events data 
-- Creating two new columns inside a CTE that have the first 7 characters (excluding the hyphens) of the Placekey column's @Where part
with new_york_attended_events_with_place_key as (
    select
        *,
        SPLIT_PART(Placekey, '@', -1) as place_key_where,
        LEFT(SPLIT_PART(Placekey, '@', -1), 9) as phq_place_key_where_first_7_chars
    from
        marketplace.predicthq.new_york_attended_events
    where
        placekey is not null
),
 
-- Selecting all the store locations from SafeGraph Global Places Q3 2022
-- Creating two new columns inside a CTE that have the first 7 characters (excluding the hyphens) of the Placekey column's @Where part
safegraph_resturant_stores as (
    select
        *,
        SPLIT_PART(Placekey, '@', -1) as place_key_where,
        LEFT(SPLIT_PART(Placekey, '@', -1), 9) as safegraph_place_key_where_first_7_chars
    From marketplace.safegraph.safegraph_global_places_sample_q3_2022 
)
 
-- Inner joining between PredictHQ’s Events and Safegraph’s Restaurant Locations on the new columns containing the first 7 characters of the Placekey’s @Where part
select
    *
from
    safegraph_resturant_stores as safegraph
    inner join new_york_attended_events_with_place_key phq_events on phq_events.phq_place_key_where_first_7_chars = safegraph.safegraph_place_key_where_first_7_chars
order by
    phq_events.phq_place_key_where_first_7_chars;

Use Snowflake to get Placekeys for your address data

See this article for details on how to use an External Function in Snowflake to get a Placekey for an address. If you have a data set in Snowflake where you have a lot of address data and you want a structured way to join it with events data and/or POI data you can use this functionality to set a Placekey for all your records. You can then use the information outlined in this article to match events and Placekey data.

Walkthrough of using Placekey with POI data

Note: The locations used in this example are not meant to be real examples of actual locations for a new store.

In this scenario, let’s say you are a business looking to open a new retail store in San Francisco. You have SafeGraph Places, Geometry, and Spend POI data. You are using SafeGraph Places data to look at competitors' locations in the area. See the SafeGraph Retail site selection guide for factors to consider when selecting a site for a new store.

Based on your analysis of POI data, you’ve identified 2 possible sites for your new store and you’re trying to decide between the different locations. You have Safegraph spend data and competitor data. Site 1 is Beale St, San Francisco, CA 94105, United States which has a Placekey of 223@5vg-7gt-tjv. Site 2 is at Taylor St in San Francisco. It has a Placekey of 229@5vg-7gw-vfz.

You can see healthy spending activity and attractive demographics in both locations and based on competitor analysis, you think both locations are good candidates. But you don’t know what is driving people to these areas. So using PredictHQ events data, you query for events in the area to get a more complete picture of what is happening around these locations.

By querying on events around these two locations, we see:

Site 1 has around 48 attended events (at the time of writing this guide) when matching the first 7 digits of the Placekey to find nearby events.
It is near the Hyatt Regency San Francisco which is an event venue. We used the query below to find events around the venue:

curl --location --request GET 'https://api.predicthq.com/v1/events?placekey=@5vg-7gt-t' \
--header 'Authorization: Bearer <token>'

Site 2 has around 545 attended events (at the time of writing this guide) when matching the first 7 digits of the Placekey to find nearby events.
It’s next to the Hilton San Francisco which is driving a lot of events that will help attract people to the store. There are also other nearby venues like A.C.T.'s Geary Theater, Curran Theatre, and an Irish Bar that holds music events often.

curl --location --request GET 'https://api.predicthq.com/v1/events?placekey=@5vg-7gw-v' \
--header 'Authorization: Bearer <token>'

Although they have similar amounts of target customer activity, the nature of the events around site 2 makes it more desirable. Taking this event and venue information into account along with other factors, the business decides to open the store in this location.

The choice of site selection for a new store or other types of business is huge. Having the right data is critical to ensure the best possible location is selected. Combining events with POI data provides an extremely powerful combination of information to find the best location.

If you have any questions about using the Placekey support on event data to join with POI data please drop us a note.