FlowsBook a callSign inCreate free accountSign up
Roads and traffic

A real time traffic speed API for your own system: speeds and jam factor per site

Get live road speeds, free-flow speeds and the jam factor around your own sites into a dispatch tool, a database or a dashboard, without building a data pipeline.

Part of the guide Location intelligence automation

By the xMap team · · 6 min read

If you need a real time traffic speed API for your own software, the simplest route in xMap Flows is a small flow that reads the roads around your sites and hands the figures to your system: either your system calls the flow through the REST API and gets the speeds back in the answer, or the flow writes each reading into your database on a timetable. Either way you get, for every site, the current speed, the speed when the roads are clear, a jam factor from 0 to 10 and the busiest road nearby.

This article is for developers, product owners and operations analysts who want live road conditions inside a dispatch tool, a customer app or an internal dashboard. It explains what the figures are, the three ways to get them out, a made-up example from a field service company in Melbourne, and what this kind of data cannot tell you.

What one reading contains

The Traffic Flow block looks at the roads around each place that reaches it and adds the same set of fields to every one, so your code can count on them being there:

  • speed_kmh and free_flow_kmh: how fast traffic moves now and how fast it moves on those roads when they are empty, averaged over the road stretches and weighted by their length.
  • jam_factor: 0 for free-flowing up to 10 for standstill or closed, and congestion_pct, how much slower than free flow.
  • traffic_level: the jam factor in words (Free flowing, Light, Moderate, Heavy, Standstill).
  • roads_measured, roads_closed and busiest_road: how many stretches were read, how many are closed and the name of the worst one.
  • traffic_confidence and traffic_updated: how sure the reading is, from 0 to 1, and when it was measured, in UTC.

You choose how far to look: the roads right next to the site (about 150 m), everything within 500 m, or within 1 km. Sites within 300 m of each other share one reading, which keeps a dense list of shops or depots quick. Numbers come rounded to one decimal, and a field is left empty when no road was measured, so test for empty values rather than zero.

Three ways to get the figures into your system

1. Your system asks, the flow answers

Build a flow that starts from your sites and reads their roads: My data with a table of your sites (name, latitude, longitude), then Traffic Flow. Your code then calls POST /v1/flows/{id}/run with an access key. The answer carries the status, each block's result and the items that reached the end of the flow, up to 500, each with the speed fields attached. With send: false nothing is sent anywhere; the data comes back to you and that is all. When a site opens or closes, your system can add it to the table with POST /v1/tables/{id}/rows, so the flow never needs editing. The API reference lists every call.

2. The flow writes, your system reads

If several tools need the numbers, or you want a history, turn it around. A Schedule runs the flow as often as every 5 minutes, and Save to my database inserts each reading into a table of your own PostgreSQL, BigQuery or Snowflake database, each field into the column of the same name. Your dashboard, your app and your analysts read that table with the tools they already use. Saving happens only in real runs, so deploy the flow with sending switched on; a test run leaves your database alone. The help article on your own database covers the connection and the write permission.

3. A sheet for lighter use

For a small team without a database, the Google Sheets app adds a row per site per run. It is the quickest to set up and the easiest to share, and it is fine for a few dozen sites read a few times a day. See Google Sheets, Docs and Drive.

A made-up example: dispatch software in Melbourne

Say a field service company in Melbourne runs its own dispatch tool for 40 technicians. Dispatchers keep promising arrival times that the morning traffic then breaks. The developer wants the tool to show, next to each of the day's job sites, how the roads around it are moving.

  1. A table in My data holds the day's job sites, refreshed each evening from the booking system through the tables API.
  2. The flow reads that table and runs Traffic Flow with Within 500 m.
  3. At 07:30 and every 15 minutes until 10:00, the dispatch tool calls the run endpoint and stores the answer.
  4. Jobs with a jam factor above 6 or a closed road nearby are flagged amber on the dispatcher's screen, with the busiest road named.

The dispatchers stop guessing. When a cluster of jobs in one suburb shows Heavy at 08:00, they swap the order of two technicians' first visits. The thresholds and times here are invented to show how the pieces fit; each team will settle on its own after a couple of weeks of readings.

Limits to design around

  • No car counts. Live speed data tells you how fast traffic moves, never how many vehicles passed. Counted cars by the hour exist only for roads in the United Arab Emirates, as the road traffic history dataset in Regional data.
  • No history on its own. A reading is taken when the flow runs. If you want last Tuesday at 08:00, you need to have stored it, which is why the database route matters.
  • Per site, not per road segment. You get an average over the roads around each point and the name of the worst one, not a feed of every street in a city or a lane-by-lane split.
  • No directions. It does not tell a driver which way to go. For the order of a day's stops, the Route planner is the block to add.
  • Closures are counted, not described. roads_closed says how many stretches are closed. For what the closure is and where exactly, add Traffic incidents.

Why a flow instead of raw calls

A raw speed feed still leaves you to handle the parts that take time: matching your sites to roads, averaging stretches, retrying when the service is busy, keeping a record and alerting someone when a reading crosses a line. A flow does those in blocks you can see. You can add a Filter that lets only Heavy or Standstill sites through, an email to the duty manager, or a second branch that writes to a different table, without touching your own code. If you prefer to start from something that already runs, the road speeds outside my depots template reads depots every hour, and road speeds around the airport does the same for one busy site. For the wider picture of connecting tools this way, see workflow automation.

Questions

Does the API give traffic for any road in the world?

It gives readings around the places you send, in cities where live road speeds are measured. You choose the points; it does not return a whole city's road network.

How fresh is a reading?

It is measured at the moment the flow runs, and traffic_updated says when. Run the flow on a timetable as often as every 5 minutes, or call it from your system whenever you need a fresh value.

Can I get the number of cars on a road?

Not from live speeds. Counted cars by hour since January 2021 exist only for roads in the United Arab Emirates, in the Regional data block.

What happens if no road is measured near a site?

The site still comes through, with the speed fields empty and traffic_level saying No roads measured. Treat empty as unknown, not as free-flowing.

Can I keep the readings for analysis later?

Yes. Save to my database writes each reading into your own PostgreSQL, BigQuery or Snowflake table on every real run, so the history is yours to query.

Templates that do this

Read next

More on roads and traffic · Every article · Templates

Put it to work

An AI employee in xMap Flows does this on live data, on its own timetable. Start from a template or describe it in plain words.