---
title: "Match your locations"
description: "Bring your own list of stores or sites and match them to Pine59's location identifiers so you can query our data using your IDs."
slug: "/docs/guides/match-locations"
last_updated: "2026-08-31"
status: "published"
industry: ["retail", "real-estate"]
location_types: ["place"]
tags: ["platform", "custom-locations", "matching"]
is_case_study: false
locked: false
related_metrics: []
related_datasets: []
example_count: 1
example_tools: ["python"]
---


# Match your locations

Bring your own list of stores or sites and match them to Pine59's location identifiers so you can query our data using your IDs.

## Metadata

- Industry: retail, real-estate
- Location types: place
- Tags: platform, custom-locations, matching

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](/docs/guides/store-profiling) of any location on it, or a [brand comparison](/docs/guides/brand-comparison) across the set.

## Examples

### Matching a store list to location identifiers _(Python · USA)_

Four San Antonio addresses matched in Python: exact address, disambiguation by brand, a value search for the one the list misspelled, and the join the mapping enables.

Full worked example: [/docs/guides/match-locations/match-addresses-api.md](/docs/guides/match-locations/match-addresses-api.md)