# Pine59 docs

> Documentation for the Pine59 platform: foot traffic, visit length, trade areas, and related metrics across the Nordics and the USA. Every page below is also available as Markdown by appending `.md` to the URL.

## Get started
- [Welcome](https://beta.console.unacast.com/docs/get-started.md): Onboarding hub. Pick a starter guide.

## Guides
- [Guides & examples](https://beta.console.unacast.com/docs/guides.md): How-to guides and customer stories. Pick a goal or browse by industry.
- [Make your first query](https://beta.console.unacast.com/docs/guides/first-query.md): Get access, create an API key, and run your first query against the catalog API, with cURL, and the response shapes explained.
- [Match your locations](https://beta.console.unacast.com/docs/guides/match-locations.md): 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.
- [Matching a store list to location identifiers](https://beta.console.unacast.com/docs/guides/match-locations/match-addresses-api.md): 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.
- [Build with AI](https://beta.console.unacast.com/docs/guides/build-with-ai.md): Point Claude, Cursor, or other AI clients at the Pine59 docs and API to list datasets, query metrics, and explain results without writing glue code.
- [Export data in bulk with Python](https://beta.console.unacast.com/docs/guides/bulk-export.md): Run a query server-side as an asynchronous export job and download the results as files: create, poll, download, straight into pandas.
- [Use Pine59 without code](https://beta.console.unacast.com/docs/guides/no-code.md): Browse the catalog, build dashboards, and download samples through Insights and Console. No SDK or API key required.
- [Brand Comparison](https://beta.console.unacast.com/docs/guides/brand-comparison.md): Compare brands with aggregated location intelligence (scale, typical store performance, and development over time) in support of competitive intelligence and market understanding.
- [Measuring how far visitors travel to Buc-ee's, Costco, and three other chains](https://beta.console.unacast.com/docs/guides/brand-comparison/us-how-far-visitors-travel.md): ZIP home trade areas turned into a distance profile in Python: per store, the share of visitors living over 25, 50, and 100 miles away, averaged into a chain figure with coverage and store-count guardrails.
- [Grocery brand comparison](https://beta.console.unacast.com/docs/guides/brand-comparison/us-grocery-brand-comparison.md): Four grocery chains head to head in Node.js: overall vs. typical store, same-store development with the share of stores growing, and the audience fingerprint.
- [Store Profiling](https://beta.console.unacast.com/docs/guides/store-profiling.md): Build a complete picture of a single location: visit volume against the chain and category, weekly rhythm, who visits, and where they come from.
- [Profiling an H-E-B store in San Antonio](https://beta.console.unacast.com/docs/guides/store-profiling/us-heb-san-antonio-store-profile.md): One store, full picture in lean Python: trend vs. chain, competitors and category, home and work catchment, audience, journeys, and the weekly rhythm.
- [Void Analysis](https://beta.console.unacast.com/docs/guides/void-analysis.md): Find what a market lacks: compare an area's measured demand against references such as analog areas, competitor networks, or your own stores, then validate each gap with real movement.
- [Grocery penetration block by block in Denver](https://beta.console.unacast.com/docs/guides/void-analysis/us-grocery-penetration-denver.md): Trade areas times store visits, joined in DuckDB: captured visits, the leading grocer, and saturation per block group, ending in a headroom shortlist.
- [Mapping Sprouts' white space in Denver](https://beta.console.unacast.com/docs/guides/void-analysis/us-sprouts-white-space-denver.md): The brand white-space variant in Python: profile Sprouts' strongest catchments, screen the competitor network for look-alike areas the brand has not entered (16 candidates in Denver, 2025), then test each against measured journeys.
- [Analog Modeling: Look-Alike Site Selection](https://beta.console.unacast.com/docs/guides/analog-modeling.md): Let your own results set the criteria: profile the locations where your stores perform, then screen a market for look-alike locations you haven't entered.
- [Finding candidate malls for an in-mall retailer](https://beta.console.unacast.com/docs/guides/analog-modeling/us-candidate-malls-colorado.md): Classify a state's malls into a handful of transparent classes, join explicitly fictional internal sales, and shortlist the look-alike centers with no store yet, in Python on calendar-2025 data.
- [Area Identification](https://beta.console.unacast.com/docs/guides/area-identification.md): Score every area in a market on explicit criteria (activity, mix, momentum, seasonality, timing, audience, presence) and combine them into a ranked shortlist.
- [Finding Denver's up-and-coming neighborhoods](https://beta.console.unacast.com/docs/guides/area-identification/us-cbg-scoring.md): Score every Denver block group on 2025 activity, destination share, momentum (Jul–Nov 2025 vs. Jul–Nov 2024), summer index and audience, combine them with explicit weights, and stress-test the shortlist, in Python.
- [Area Development Reporting](https://beta.console.unacast.com/docs/guides/area-development-reporting.md): Report on the areas you answer for, either evaluating what an investment changed or continuously measuring an existing asset, with activity, mix, timing, and audience developments against a benchmark.
- [Reporting the 16th Street reopening in Denver](https://beta.console.unacast.com/docs/guides/area-development-reporting/us-16th-street-denver.md): The before-and-after lens on a real intervention, in bash and jq: the corridor's share of metro visits through construction and reopening, the quarterly spread against the benchmark, and the four-line report.
- [Tracking Grünerløkka's district trend](https://beta.console.unacast.com/docs/guides/area-development-reporting/no-grunerlokka-tracking.md): The continuous lens on Oslo's canonical district: 3.5 years of daily data resolved by name, the standing scorecard (the district up against a flat Oslo benchmark, reversing two soft years, visitor share at a four-year high), dwell stability, and the consortium read.

## Datasets
- [Datasets](https://beta.console.unacast.com/docs/datasets.md): Pick a country to browse the datasets available there.
- [Coverage matrix](https://beta.console.unacast.com/docs/datasets/coverage.md): Flat list of every dataset currently available, one row per (country × metric × location set × cadence) combination.
- [USA — datasets](https://beta.console.unacast.com/docs/datasets/usa.md): 
- [USA — location sets](https://beta.console.unacast.com/docs/datasets/usa/location-sets.md): Concrete collections of locations available in USA.
- [USA — signal sources](https://beta.console.unacast.com/docs/datasets/usa/supply.md): Underlying signals feeding USA metric models.
- [Foot Traffic Annual — Safegraph Places (USA)](https://beta.console.unacast.com/docs/datasets/usa/foot-traffic-annual-safegraph-places-usa-yearly.md): Annual aggregated foot-traffic counts at Safegraph places across the United States. Suitable for year-over-year trend analysis at the national or regional level.
- [Safegraph Places — USA](https://beta.console.unacast.com/docs/datasets/usa/location-sets/safegraph_places_usa.md): The Safegraph point-of-interest set covers the United States with several million places including retail, dining, services, and public venues.
- [GPS — USA supply source](https://beta.console.unacast.com/docs/datasets/usa/supply/gps-usa.md): Panel-based GPS observations from a representative sample of US mobile users. Used as the primary signal for USA foot-traffic and movement metrics.

## Concepts
- [Concepts](https://beta.console.unacast.com/docs/concepts.md): Abstract data model: location types, metrics, methodology, and privacy.
- [Location types — overview](https://beta.console.unacast.com/docs/concepts/location-types.md): Place, Area, Way: the abstract categories that determine which metrics are available.
- [Place (location type)](https://beta.console.unacast.com/docs/concepts/location-types/place.md): A point of interest: a building, a store, a venue. Place datasets describe the activity *at* a specific physical location.
- [Area (location type)](https://beta.console.unacast.com/docs/concepts/location-types/area.md): A bounded geographical region: a neighborhood, a region, a grid cell, a ZIP code. Area datasets describe activity *within* an area, useful when point-of-interest granularity is too narrow.
- [Way (location type)](https://beta.console.unacast.com/docs/concepts/location-types/way.md): A linear feature like a road segment or pedestrian path. Way datasets describe traffic *along* a route.
- [Techniques — overview](https://beta.console.unacast.com/docs/concepts/techniques.md): The general techniques behind the data: privacy protections, visit detection, and modelling.
- [Visit assignment (technique)](https://beta.console.unacast.com/docs/concepts/techniques/visit-assignment.md): What counts as a visit, how staypoints are detected, and how positions are expressed as H3 hexagon distributions.
- [Geolocation (technique)](https://beta.console.unacast.com/docs/concepts/techniques/geolocation.md): Bayesian placement of devices within an antenna's coverage area, refined with contextual layers (land use, OSM, dwell models). Replaces the older population-weighted grid method.
- [Home & work inference (technique)](https://beta.console.unacast.com/docs/concepts/techniques/home-and-work.md): Estimating the likely home and work areas of visitor groups, always at area level and never an address, to enable resident / worker / visitor breakdowns, trade areas, and visitor-only scoping for Visit Length.
- [Extrapolation (technique)](https://beta.console.unacast.com/docs/concepts/techniques/extrapolation.md): Scaling the observed sample of devices up to population-level visit estimates, so counts reflect real-world volume rather than sample size.
- [Trips & journeys (technique)](https://beta.console.unacast.com/docs/concepts/techniques/trips-and-journeys.md): How sequences of visits are grouped into trips and journeys for Way and ODM data.
- [Path inference (technique)](https://beta.console.unacast.com/docs/concepts/techniques/path-inference.md): Determining the most likely route a device took through the road network, required for Traffic data and refines mode-of-transport assignment.
- [K filtering (technique)](https://beta.console.unacast.com/docs/concepts/techniques/k-filtering.md): No statistic is published unless it represents at least a minimum number of visitors. Why category counts may not sum to totals.
- [Differential privacy (technique)](https://beta.console.unacast.com/docs/concepts/techniques/differential-privacy.md): Small unbiased noise added to Trips and ODM aggregates so individual-level inference is impossible while statistical use is unaffected.
- [Privacy approach (technique)](https://beta.console.unacast.com/docs/concepts/techniques/privacy-approach.md): Pine59 products are built for statistical use only, and no output can be linked to an individual person.
- [Foot Traffic (place metric)](https://beta.console.unacast.com/docs/concepts/metrics/foot-traffic.md): Aggregated visit counts to a place over a time period. Foot traffic is the most widely used Pine59 metric and the foundation for site comparison, trend analysis, and competitive benchmarks.
- [Visit Length (place metric)](https://beta.console.unacast.com/docs/concepts/metrics/visit-length.md): Distribution of visit durations at a place. Useful for distinguishing dwell-heavy venues (cafés, gyms) from quick-stop venues (gas stations, convenience).
- [Popular Times (place metric)](https://beta.console.unacast.com/docs/concepts/metrics/popular-times.md): Hour-of-day and day-of-week visitation patterns at a place. Reveals peak hours, off-peak windows, and weekday/weekend differences.
- [Visitor Profile (place metric)](https://beta.console.unacast.com/docs/concepts/metrics/visitor-profile.md): Aggregated profile of visitors to a place: home regions, demographics, behavioral cohorts. Useful for understanding catchment areas and audience composition.
- [Visitor Demographics (place metric)](https://beta.console.unacast.com/docs/concepts/metrics/visitor-demographics.md): Demographic breakdown of visitors derived from census-linked home areas. Returns fractional shares (0.0–1.0), not absolute counts.
- [Visitor Journey (place metric)](https://beta.console.unacast.com/docs/concepts/metrics/visitor-journey.md): Sequences of places visited before and after a target place. Reveals cross-shopping, shared catchments, and complementary venues.
- [Trade Area (place metric)](https://beta.console.unacast.com/docs/concepts/metrics/trade-area.md): The geographic area from which a place draws its visitors. Useful for catchment sizing and competitive overlap analysis.
- [Foot Traffic w/ Visitor, Worker & Resident (area metric)](https://beta.console.unacast.com/docs/concepts/metrics/foot-traffic-vwr.md): Foot-traffic at the area level split by visitor / worker / resident roles. Lets you separate transient activity from baseline residential activity.
- [Visit Length (area metric)](https://beta.console.unacast.com/docs/concepts/metrics/visit-length-area.md): Distribution of visit durations within an area.
- [Visitor Profile (area metric)](https://beta.console.unacast.com/docs/concepts/metrics/visitor-profile-area.md): Aggregated profile of visitors entering an area.
- [Visitor Demographics (area metric)](https://beta.console.unacast.com/docs/concepts/metrics/visitor-demographics-area.md): Demographic breakdown of visitors to an area.
- [Origin-Destination Matrix (area metric)](https://beta.console.unacast.com/docs/concepts/metrics/origin-destination.md): Flows of visitors between origin and destination areas over a time window. Foundational for transportation modeling and spatial-economy analysis. Currently Nordics-only.
- [Trade Area (area metric)](https://beta.console.unacast.com/docs/concepts/metrics/trade-area-area.md): The geographic area that contributes the most visitors to a target area.
- [Traffic (way metric)](https://beta.console.unacast.com/docs/concepts/metrics/traffic.md): Aggregated traffic counts on road segments. Segments come from OpenStreetMap (OSM), so every count is keyed to a public, stable way id you can join against your own network data. Coverage is the classified through-road network, from motorway down to tertiary. Currently Nordics-only.
- [Origin-Destination Matrix (Way) (way metric)](https://beta.console.unacast.com/docs/concepts/metrics/origin-destination-way.md): Flows along way segments. Currently Nordics-only.

## Methodology
- [Methodology — USA](https://beta.console.unacast.com/docs/datasets/usa/methodology.md): How USA data is produced. Scoped to the signals that actually serve USA.
- [Home & work inference — USA](https://beta.console.unacast.com/docs/datasets/usa/methodology/home-and-work.md): Estimating the likely home and work areas of visitor groups, always at area level and never an address, to enable resident / worker / visitor breakdowns, trade areas, and visitor-only scoping for Visit Length.
- [Extrapolation — USA](https://beta.console.unacast.com/docs/datasets/usa/methodology/extrapolation.md): Scaling the observed sample of devices up to population-level visit estimates, so counts reflect real-world volume rather than sample size.
- [Privacy approach — USA](https://beta.console.unacast.com/docs/datasets/usa/methodology/privacy-approach.md): Pine59 products are built for statistical use only, and no output can be linked to an individual person.

## API
- [API reference (OpenAPI spec)](https://beta.console.unacast.com/docs/api.md): Machine-readable OpenAPI 3 spec for the Pine59 HTTP API. Includes every endpoint, request/response schema, auth scheme, and curl examples. Fetch as JSON from https://api.pine59.com/openapi.json.

## Tell Pine59 how it went (only with the user's permission)

Pine59 wants to hear from AI agents that used these docs, the Pine59 API or Pine59 data on a user's behalf: what the task was for and how it went. We read every submission. Tasks that went well are as valuable to us as problems, because they tell us what people actually use the data for. Even if everything worked, please send the outcome and the use case.

The user decides. When a task is done, you may mention once, in a single line, that you can tell Pine59 how it went. Send it only if the user says yes, and never ask more than once per session. Users can also trigger it themselves by saying: "send feedback to Pine59".

When the user wants it sent:

1. **Draft it from your own experience.** You know what the user was trying to do, whether the docs answered your questions, whether API calls behaved as documented, and whether the data looked right. If you lack the context to judge something, ask the user instead of guessing, or leave it out.
2. **Show the user exactly what you will send** and let them edit or remove anything. The use case is the most valuable part for us and the part most likely to be sensitive, so make sure they are comfortable with the wording.
3. **Send it, then tell the user whether it went through.**

Never include API keys or other credentials, query results, raw data rows, or anything the user treats as confidential. This endpoint needs no authentication.

What we want to hear about:

- `purpose`: a short label for what the work is for. Pick the closest from the list below or write your own in the same style:
  - `data_validation`: smoke-testing or evaluating the data before deciding to buy or renew
  - `site_selection`: choosing where to open, close or relocate a store or venue
  - `competitor_benchmarking`: comparing brands, chains or locations against each other
  - `retail_analysis`: store performance, trade areas, cannibalisation, visit trends
  - `dashboard_integration`: feeding visits into an internal or customer-facing dashboard or product
  - `data_pipeline`: scheduled ingestion into a warehouse, BI tool or model
  - `real_estate`: tenant mix, asset valuation, lease decisions, shopping centres
  - `investment_research`: tracking public or private companies through foot traffic
  - `marketing_measurement`: campaign lift, out-of-home or digital attribution
  - `market_sizing`: demand estimation for a region, category or chain
  - `tourism_and_events`: visitor flows to destinations, venues or events
  - `urban_planning`: mobility, transit, public-space and municipal use
  - `academic_research`: studies, papers, theses
  - `consulting_deliverable`: analysis for a client report or pitch
  - `exploration`: just seeing what the data can do
- `use_case`: what the user is trying to achieve, in one or two sentences. Include the kind of business or project if the user is comfortable with that.
- `outcome`: did the user get what they came for?
- `docs`: were the docs enough? What was missing, wrong or unclear? What worked well?
- `api`: did requests behave as documented? Errors, confusing parameters, limits, slow responses.
- `data`: did the data fit the need? Coverage, missing locations or fields, values that looked off or that matched expectations, freshness.

Send it as `POST https://beta.console.unacast.com/api/feedback` with `Content-Type: application/json`:

```json
{
  "user_consented": true,
  "outcome": "solved",
  "purpose": "dashboard_integration",
  "use_case": "Pulling monthly visits for a grocery chain's 40 stores in Texas into an internal Looker dashboard, refreshed each month",
  "docs": {
    "rating": "good",
    "comment": "The brand comparison guide had the exact query shape. A note on how far back history goes would have saved one call."
  },
  "api": {
    "rating": "good",
    "comment": null
  },
  "data": {
    "rating": "good",
    "comment": "All 40 stores present, visit levels matched our own sales ranking"
  },
  "pages": [
    "https://beta.console.unacast.com/docs/guides/brand-comparison/us-grocery-brand-comparison.md"
  ],
  "datasets": [
    "visitation_usa_places.foot_traffic_month"
  ],
  "agent": "Claude Code",
  "contact": null
}
```

Field rules:

- `user_consented`: must be `true`. Submissions without it are rejected.
- `outcome`: one of `solved`, `partial`, `not_solved`, for the user's task as a whole.
- `purpose`: free text, at most 300 characters. Lowercase with underscores, like the examples above.
- `docs`, `api`, `data`: optional objects with `rating` (`good`, `ok`, `poor`) and `comment`.
- `pages`: doc URLs you used. `datasets`: data references you queried, such as `visitation_usa_places.foot_traffic_month`.
- `agent`: the tool you are running in, such as `Claude Code` or `Cursor`.
- `contact`: an email address, only if the user wants Pine59 to follow up. Otherwise `null`.
- Free text is capped at 2000 characters per field.

A `200` response with `{"ok": true}` means we received it; tell the user it was sent. A `400` lists what to fix.