canonical: https://jentic.com/apis/o2.cz/o2-mobility-api

# O2 Cz Mobility API

The O2 Mobility API exposes time-aggregated transit data describing how people move between basic residential units (ZSJ) within the Czech Republic. The data is anonymised and derived from O2 Czech Republic mobile network signalling, so each query returns counts of devices travelling between an origin and a destination over a chosen time window. It is intended for transport planning, retail catchment analysis, and tourism research that need flow data rather than individual location pings.

## For AI agents

Retrieve anonymised counts of people travelling between Czech residential units, sourced from O2 Czech Republic mobile network signalling.

## Scope

Does not return individual identities, real-time GPS, or device-level traces - use for anonymised, time-aggregated origin-destination counts within the Czech Republic only.

## Capabilities

- Query device counts travelling between two Czech basic residential units (ZSJ) for a chosen window
- Aggregate transit volumes by hour or day to expose commute, weekend, and event patterns
- Compare inbound and outbound flows for a single ZSJ to estimate catchment areas
- Inspect dataset and application version metadata via /info before running batch queries
- Feed anonymised origin-destination counts into transport, retail, and tourism dashboards

## Use cases

### Origin-destination matrix for Czech transport studies

Build an origin-destination matrix between residential units across a Czech region by iterating over ZSJ pairs and pulling aggregated transit counts. The Mobility API returns anonymised counts derived from O2 mobile signalling, so a transport consultant can compose a regional flow matrix without commissioning a household travel survey. Outputs feed directly into demand modelling tools.

Example prompt: For each ZSJ pair in a region, call GET `/transit/{from}/{to}` with a one-week window and assemble the results into an origin-destination matrix

### Retail footfall origin estimation

Identify which residential areas send shoppers to a retail destination by ranking inbound transit counts from surrounding ZSJs into the destination ZSJ. The API exposes hour-level aggregates so an analyst can isolate trading hours and weekends, and feed the rankings into a catchment map. The data is anonymised, which makes it usable for marketing planning without privacy review delays.

Example prompt: Pull /transit from each surrounding ZSJ into a retail centre ZSJ across the last 30 trading days and rank origins by inbound count

### Event impact monitoring

Measure how a festival, sports match, or transport disruption changes movement patterns by comparing transit counts on event days against a baseline week. Querying both inbound and outbound flows for affected ZSJs reveals the size and direction of the swing. Because the dataset is hour-aggregated, agents can correlate spikes with the event timeline.

Example prompt: Compare /transit counts into a festival venue ZSJ on event days vs a baseline weekend and report the percentage uplift per hour

### AI agent integration via Jentic

An analytics agent searches Jentic for Czech mobility data, loads the GET `/transit/{from}/{to}` schema, and pulls inbound counts to answer questions like 'how did weekend visitors change after the new tram line opened?'. Jentic exposes the validated operation so the agent can call it with structured arguments and convert the response into a written narrative.

Example prompt: Use Jentic to search 'czech transit between residential units', load the operation schema, and execute it with from and to ZSJ codes for the last weekend

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/transit/{from}/{to}` | Counts of people travelling between two basic residential units |
| GET | `/info` | Application and data version information |

## Key resources

- **Transit** — Hour- or day-aggregated counts between two basic residential units
- **Info** — Application and data version metadata

## Why Jentic

- **Setup:** Wiring the O2 Mobility API by hand means pointing at the developer.o2.cz sandbox host, handling any move to production access separately, and coding your own retry and rate-limit handling. Through Jentic you install once, import the Mobility API from the API Directory, store any production key once, and your agent calls it.
- **Permission scoping:** This API returns anonymised, time-aggregated origin-destination counts through read-only GETs, so scope it by operation: limit the agent to the transit-count and info operations it needs and nothing else. You choose which operations it may call, so no other behaviour runs unless you add it.
- **Credential handling:** Any production access key is stored once, encrypted, by your own Jentic One instance and injected at execution time, so the agent never sees the raw key. Sandbox calls that need no auth still flow through Jentic's logging and retry layer.
- **Discovery method:** Agents search Jentic by intent such as 'Czech origin-destination counts', and Jentic returns the GET `/transit/{from}/{to}` operation with its input schema so the agent calls the right endpoint without reading the underlying spec.

## Related APIs

- **O2 Socio-demo API** — Same O2 Liberty programme - adds age and gender breakdowns for a location
- **HERE Maps APIs** — Global mobility, routing, and traffic data - broader geographic scope than the Czech-only O2 dataset
- **TransitFeeds** — GTFS public transport schedule feeds - pair with O2 mobility counts to compare scheduled supply with realised demand

## FAQ

### What authentication does the O2 Mobility API use?

The published spec for the sandbox base URL does not declare any security schemes, so sandbox calls to `/transit/{from}/{to}` and /info go through unauthenticated. Production access via the Liberty Developer programme requires a developer key; through Jentic any such key is held in the vault and injected at runtime, never surfacing in the agent's prompt.

### Can I retrieve hourly origin-destination counts with the Mobility API?

Yes. GET `/transit/{from}/{to}` accepts time range parameters and returns hour- or day-aggregated counts of devices travelling between the two basic residential units, derived from O2 Czech Republic mobile signalling.

### Does the Mobility API expose individual locations or trajectories?

No. The API only returns aggregated transit counts between residential units. There is no endpoint for live device positions, individual identifiers, or per-trip routes, which keeps the dataset compatible with Czech privacy norms.

### What are the rate limits for the O2 Mobility API?

The OpenAPI spec does not publish explicit rate limits for the sandbox endpoint. Treat sandbox use as best-effort and contact libertyapi@o2.cz for production quotas. When used through Jentic, agents can pace calls in their loop to avoid bursts.

### How do I build an origin-destination matrix through Jentic?

Install the Python SDK with pip install jentic, run a search for 'transit between Czech residential units', load GET `/transit/{from}/{to}`, and iterate the operation across ZSJ pairs. Jentic returns each call's JSON so the agent can assemble the matrix without parsing the swagger by hand.

### How do I confirm the dataset has been refreshed?

Call GET /info. The endpoint returns application and data version strings so a pipeline can detect refreshed extracts and pin a known dataset version for reproducible analysis.

### Can I limit what my agent is allowed to do with the O2 Mobility API?

Yes. Because you run Jentic One yourself, your own rules decide which operations the agent may call, so you can grant only the read-only transit-count operation (GET `/transit/{from}/{to}`) and the version-check operation (GET /info) and nothing else. The API exposes only these anonymised, time-aggregated origin-destination GETs, so scoping it to those two operations means the agent cannot reach any other behaviour. Any production access key is held by your instance and injected at execution time, so the agent never sees the raw credential.