Match your locations

Our Places metrics are keyed on a location identifier, and most of the value of the data comes from joining it to a list you already have: your stores, your sites, a competitor set from a broker, a lease pipeline. This guide covers how our identifiers work, how to match your list to them, and how to keep the mapping sound.

1. The identifier

Every place in our directory carries a location_id. For US places it is the location's Placekey, an open identifier that encodes the address and the point of interest on it. If your list already carries Placekeys, there is nothing to match: filter on location_id and you are done. If it carries addresses, names, or your own store numbers, you match once and keep the mapping.

2. Matching by address

The places directory holds the fields a match needs: street address, city, region, postal code, name, and brand. Matching runs in three passes, and stops for each record at the first pass that resolves it:

• Exact address. Street address plus postal code, or plus city, as an exact filter. An address usually returns more than one record: the store, its pharmacy, its fuel station, the tenants in the same building. That is not noise, it is the directory being complete.
• Disambiguation. Narrow the records at an address by brand or name to the one your list means. A store list means the store, not its pharmacy.
• Search. Where exact matching finds nothing, the usual cause is formatting: a suite number, an abbreviation, a renamed road. A value search on the address field finds the directory's spelling; re-run the exact match with it.

What is left after three passes is unmatched, and should stay that way in your mapping rather than be forced to the nearest record. A location that is not in the directory has no visitation data to join to.

3. Keeping the mapping

Store the mapping as a table of your identifier against location_id, with the pass that produced each match. Two rules keep it sound:

• Re-verify on a cadence. The directory changes: places open, close, move, and get re-identified. A mapping older than a quarter deserves a re-run of the exact pass against the current directory.
• Match once, join everywhere. Every metric dataset carries the same location_id, so one mapping serves foot traffic, trade areas, visitor profiles, and journeys alike.

Once a list is mapped, the natural next step is a store profile of any location on it, or a brand comparison across the set.