Custom Locations

This is an enterprise service. Send an inquiry to Unacast about your interest.

Obtain foot traffic for custom locations on demand. This API allows you to submit requests for foot traffic reports on your custom polygons.

These APIs are currently only available over gRPC. Below in the examples you will find the currently supported language clients. Other language clients can be provided on request.

Constraints

• US locations are supported
• Up to 500 locations can be provided per report

Metric Models

metric_id	more info
foot_traffic_week_202401	Foot Traffic w/Visit Length
foot_traffic_month_202401	Foot Traffic w/Visit Length
popular_times_202408	Popular Times (limitation of max 70k sqm per polygon)
trade_areas_quarterly_202401	Trade Area
trade_areas_zip_quarterly	Trade Area
demographics_quarterly_202401	Visitor Demographics
spatialai_personalive_quarterly_202401	Premium option. Visitor Phychographics with SpatialAI PersonAlive segments.

Examples

Python

pre-requisites

• install the python-language client: pip install unacatlib

import datetime
from unacatlib.byo_external import BYOApiClient, ReportJob

# Sample geo json, currently accepting only geojson of **FeatureCollection** of **Polygon** types.
poi_geo_json='{"type":"FeatureCollection","features":[{"type":"Feature","properties":{"name": "my-given-location-name"},"geometry":{ "type": "Polygon", "coordinates": [ [ [-122.276737859, 37.8439032810001], [-122.276899008, 37.8438818770001], [-122.276870739, 37.84375312], [-122.276741817, 37.8437702410001], [-122.276711462, 37.8437830560001], [-122.276737859, 37.8439032810001] ] ] }}]}'

def run():

    with BYOApiClient(
        billing_account="<ID you'll be provided>",
        token="<Token you'll be provided>",
    ) as client:
        metric_ids = ["foot_traffic_week_202401"]
        job: ReportJob = client.create_us_report(
            pois=poi_geo_json,
            metric_ids=metric_ids,
            start_date=datetime.date(year=2024, month=3, day=1),
            end_date=datetime.date(year=2024, month=4, day=30)
        )

        report_id = job.id

        # Polling for the completion of the report
        max_wait_minutes = 60
        check_interval_seconds = 10

        max_iterations = (max_wait_minutes * 60)
        iterations = 0

        status_code = None
        metric_values = None
        while iterations < max_iterations:
            try:
                # Try to read the report to check its status
                metric_values = client.read_us_report(report_id=report_id, metric_id=metric_ids)
                status_code = metric_values.report_status.value

                # Check if the report is completed
                if status_code == 3:  # SUCCEEDED
                    print(f"\n✅ Successfully retrieved {len(metric_values.values)} data points!")
                    print({"schema": metric_values.schema.to_json(), "values": list(map(lambda mv: mv.to_json(), metric_values.values))})
                elif status_code == 5:  # COMPLETED_WITH_ERRORS
                    print(f"\n Completed with ERRORS retrieved {len(metric_values.values)} data points!")
                elif status_code == 4:  # FAILED
                    print(f"\n❌ Error reading report data, status_code: {status_code}")

                iterations += 1
            except Exception as e:
                print(f"Error checking report status: {e}")
                iterations += 1

run()

Notebook example

Link to colab notbook example