Local Category & Location Trends from Place Data

Turn two or more dated place datasets you already have into a clear picture of how business categories are distributed across locations, and how that distribution changed between snapshots. Every row carries sample-size warnings, so thin data is not mistaken for a trend.

This Actor analyzes data you supply. It does not scrape Google Maps or any other website and makes no requests to third-party sites.

What it does

1. Reads each snapshot (inline rows or an existing Apify dataset you can access).
2. Removes duplicate places inside each snapshot (by place ID, CID or URL, otherwise by name + address).
3. Counts places per category and per location (country, state, city or postal code), plus an all-locations total.
4. Compares consecutive snapshots (or first vs last) and reports count change, category share within each location, and share change in percentage points.
5. Flags each row as likely_shift, no_clear_change or insufficient_sample.

Typical uses

• Local-market analysts checking whether a category is growing or shrinking in specific cities.
• Agencies and franchise teams tracking category mix in territories they already export data for.
• Anyone who has periodic place exports and needs a repeatable change report instead of manual spreadsheet pivots.

Input

Field	Meaning
snapshots	At least two objects with date (YYYY-MM-DD or YYYY-MM), optional label, and either items (rows) or datasetId.
geoLevel	country, state, city (default) or postalCode.
comparisonMode	consecutive (default) or first_vs_last.
minGeoSample	Minimum unique places per location in both snapshots (default 30).
minCellCount	Minimum places in a category in at least one snapshot (default 5).
minShareChangePct	Minimum share movement, in points, to call a likely shift (default 2).
maxRowsPerComparison	Output cap per snapshot pair (default 500).
maxItemsPerSnapshot	Read cap per snapshot (default 50,000).

Recognised row fields: category from categoryName, category, mainCategory, primaryCategory, type or the first entry of categories; location from countryCode/country, state/region/province, city/town/locality, postalCode/zip/postcode.

Example input (also the default prefill):

{
  "snapshots": [
    {"date": "2026-01-01", "label": "January export", "items": [
      {"placeId": "a1", "categoryName": "Coffee shop", "city": "Springfield"},
      {"placeId": "a3", "categoryName": "Bakery", "city": "Springfield"}
    ]},
    {"date": "2026-04-01", "label": "April export", "datasetId": "YOUR_DATASET_ID"}
  ],
  "geoLevel": "city",
  "minGeoSample": 30
}

The prefilled sample is tiny on purpose and will show insufficient_sample warnings; use your real exports for meaningful results.

Output

The default dataset holds three row types (recordType):

• category_geo_change – one row per location and category per comparison, with counts, shares, shareChangePoints, direction (new, dropped, up, down, flat), zScore, signal and warnings.
• comparison_summary – totals per snapshot pair, including likely-shift counts and truncation notes.
• snapshot_summary – per snapshot: input rows, unique places, duplicates removed, missing category/location percentages and warnings.

Warnings explained

• low_location_sample – a location has fewer unique places than minGeoSample in either snapshot.
• low_category_count – the category has fewer than minCellCount places in both snapshots.
• coverage_mismatch – one snapshot has more than twice the unique places of the other; the snapshots probably do not cover the same area or search, so changes may reflect coverage rather than the market.
• small_snapshot, many_missing_categories, many_missing_locations, many_duplicates, empty_snapshot, location_missing_in_one_snapshot, rows_truncated.

Limitations

• Results describe your datasets, not the whole market. If two exports were collected with different searches, areas or limits, differences may be artifacts of collection.
• Category names are compared as lowercase text. Different labels for the same business type are not merged, and no translation is done.
• Rows without a recognised category or location are counted under (unknown), and the percentage is reported in the snapshot summary.
• Locations are read from structured fields only; addresses are not parsed.
• The z-score is a rough indicator. Snapshots overlap (the same places appear in both), which violates the independence assumption, so it is not a formal significance test. Small samples can still produce misleading shares.
• Places without any ID or name + address cannot be de-duplicated.
• At most 24 snapshots and 200,000 rows per snapshot are read.

Pricing

The code defines one pay-per-event event name, category-trend-row, applied to category_geo_change rows only. Summary rows are free. Invalid input fails the run before any rows are produced, so failed runs produce no charged events. The actual price is set by the publisher in Apify Console and is not part of this repository.

Data and compliance

Only use data you are entitled to process. Place datasets can contain business contact details; this Actor reads only category and location fields for counting and does not output individual place records.