Foot traffic data API: getting footfall into your own system
How to pull footfall for your places into your own database, dashboard or app from code, which call returns live figures today, and how to design around the ten-day delay.
Part of the guide Location intelligence automation
If you want a foot traffic data API for your own software, the dependable route in xMap Flows today is to build a small flow that measures your places with Mobility Footfall, then run it from your code with one call and read the figures from the answer, or have the flow write them straight into your database. The figures you get back are averages over a window that ends about ten days ago, because each day's footfall arrives about ten days late, and your design should expect that from the start.
This article is for developers and data teams who want footfall next to their own sales, rota or site data rather than in someone else's dashboard. It covers the three ways to get the figures out, what the fields mean for a database schema, how to handle the delay, and the mistakes that make footfall tables misleading.
What exists, and what is still sample
The REST API has a data endpoint, POST /v1/data/mobility, but its answers are sample data for now and say so with "sample": true. Use it to shape your code, not for decisions. Live footfall comes from flows: a flow with the Mobility Footfall block measures real places, and the API runs that flow for you. The API reference lists every endpoint; this article only uses the ones below.
Three ways to get the figures out
| Route | Best when | What your code does |
|---|---|---|
| Run a flow and read the answer | Your system asks on demand, a few places at a time | Calls POST /v1/flows/{id}/run and reads the items in the answer |
| Add rows, let the flow react | Places appear in your system over time | Calls POST /v1/tables/{id}/rows; a live flow on New rows measures them |
| Let the flow write to you | You want a table that fills itself on a schedule | Nothing: the flow runs on a Schedule and saves rows to your database |
Routes from xMap Flows into your own system.
Run a flow and read the answer
Build a flow that starts from My data (a table of your places with latitude and longitude) or from flow variables, then Mobility Footfall. Test it in the editor until the fields look right. Then create an access key under Settings, API keys, and call POST /v1/flows/{id}/run. With send: false it is a test run; with send: true it is a real run like Run once in the editor. The answer holds each block's result and up to 500 items that reached the end, each place with its footfall fields. If a run carries on in parts, GET /v1/runs/{id} gives its status later, and GET /v1/runs/{id}/steps/{block}/items pages through every item one block passed on, kept 30 days.
If you prefer a call with named inputs, offer the flow as an AI employee and call POST /v1/employees/{name}/run with {"input": {...}}; its inputs come from a Form page's fields or the flow's variables. A run longer than about 45 seconds answers status: "running" and carries on by itself.
Add rows and let the flow react
Keep a table in My data for the places you track. When your system adds a site, it calls POST /v1/tables/{id}/rows. A live flow that starts on New rows of that table runs on the new rows only, measures them, and passes the result on. The answer to your call says how many flows started.
Let the flow write to you
For a growing history, skip the polling altogether. A Schedule, My data, Mobility Footfall and Save to my database write each place's figures into a PostgreSQL, BigQuery or Snowflake table every week. Each field goes into the column of the same name. This is the shape most analytics teams end up with, and it fits the wider idea of location intelligence automation: the data arrives on its own and your queries do the rest.
Fields worth a column
- footfall_daily: the average day's people-hours of presence in the window. A busyness measure, not a count of visitors.
- footfall_from, footfall_to, footfall_days: the days the average covers and how many had data. Make these part of the row's identity.
- footfall_peak_hour, footfall_peak, footfall_by_hour: the busiest hour, its average, and the whole day hour by hour as text you can split into 24 columns.
- footfall_morning_pct, footfall_midday_pct, footfall_evening_pct, footfall_night_pct: the share of the day in each part.
- busiest_day, quietest_day, footfall_trend_pct: the shape of the week and the last 7 days against the 7 before.
- footfall_timezone: the zone the hours are counted in. Essential when places span countries.
- footfall_note: why a place has no figures, or that the figures are from fewer or older days than asked.
Designing around the delay
Each day's footfall reaches xMap Flows about ten days after the day, and the data starts on 17 October 2026. So a window of "the last 7 days" means the seven days that end roughly ten days ago, and when even those are late the block uses the newest days there are and says so in footfall_note. Three habits follow from that:
- Store the window, not the run date, as the period a row describes. Key each row on your place id plus footfall_to.
- Run weekly rather than daily. Daily runs of a 7-day window give rows that overlap by six days and move very little.
- Never join footfall to last week's sales directly. Join on the dates the footfall row covers, so a Tuesday's people-hours sit next to that Tuesday's till receipts.
A made-up example
Say a bubble tea chain with stores in Paris, Singapore and Mexico City keeps its sales in BigQuery and wants footfall beside them. Its flow runs every Monday at 05:00, reads the 40 stores from a My data table, measures each with Mobility Footfall over the last 14 days, and saves the rows to a footfall table keyed on store id and footfall_to. When the property team adds a candidate site to the table through the API, a second flow on New rows measures it the same morning. The analysts' weekly query divides sales by footfall_daily for the same dates and flags stores where the ratio falls three weeks running. The numbers in this example are invented; the pattern is the point.
Limits to know
- At most 50 places a run; split a larger network across tables or runs.
- Footfall covers most of the world from 17 October 2026, not yet Australia. Where visitors come from is measured in Sao Paulo only so far.
- Everything is an aggregate: no person, device or single trip ever leaves xMap.
Questions
Is there a live footfall endpoint I can call directly?
Not yet: the data endpoint answers with sample data for now. For live figures, run a flow with Mobility Footfall through the API, or let the flow save rows to your database.
Why are the newest figures ten days old?
Each day's footfall arrives about ten days after that day. The block's window ends there, and footfall_from and footfall_to say exactly which days a row covers.
Is footfall a count of visitors?
No. It is people-hours of presence around the place, so someone who stays three hours counts three times. Compare places and periods with each other, not with ticket or door counts.
How do I authenticate?
With an access key in the Authorization header as a Bearer token. Create it under Settings, API keys; organization keys for systems are made on the Team page.
Can I get one row per day?
The block returns averages over the window, not a daily series. A weekly run that stores each window builds the history over time.