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

# 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 given hour or day. It is intended for transport planners, retail location analytics, tourism research, and academic mobility studies.

## For AI agents

Retrieve anonymised, time-aggregated counts of people travelling between Czech residential units, sourced from O2 Czech Republic mobile network data.

## Scope

Does not return individual identities, GPS traces, or real-time location pings - 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 time window
- Aggregate transit volumes by hour or day to spot commute, weekend, and seasonal patterns
- Filter inbound or outbound flows for a single residential unit to estimate catchment areas
- Inspect API and dataset version metadata via the /info endpoint to align downstream pipelines
- Feed anonymised mobility counts into transport planning, retail siting, and tourism dashboards

## Use cases

### Retail catchment analysis in the Czech Republic

Estimate where shoppers travel from when visiting a retail location by querying inbound transit volumes to the destination ZSJ from surrounding residential units. The Mobility API returns anonymised, hour-aggregated counts derived from O2 mobile signalling, which lets analysts rank source areas without collecting personal data. A typical catchment study can be assembled in a day from a handful of paired calls.

Example prompt: Call GET `/transit/{from}/{to}` for each candidate origin ZSJ into the destination shopping centre ZSJ over the last 30 days and rank origins by total inbound count

### Commuter flow monitoring for transport planning

Track how commuters move between residential and work areas across the Czech Republic by retrieving hour-aggregated transit counts between origin and destination ZSJs. Because the data covers the O2 subscriber base scaled to population, planners can compare morning and evening peaks across weeks and detect shifts after timetable or road changes. The dataset updates regularly, so dashboards can refresh without scraping.

Example prompt: Pull /transit between a residential ZSJ and a city-centre ZSJ for the 06:00-09:00 window across the last 14 weekdays and compute the average peak flow

### Tourism demand measurement

Quantify visitor demand for tourist regions by aggregating inbound transit counts from non-local ZSJs into a destination region. The Mobility API exposes time-aggregated movement data without identifying individuals, which makes it suitable for regional tourism boards measuring seasonality, weekend spikes, and event impact. Combining several origin-destination pairs gives a defensible estimate of visitor origin mix.

Example prompt: Aggregate /transit calls from all non-local ZSJs into a tourist destination ZSJ across summer weekends and report the top 10 origin regions

### AI agent integration via Jentic

An AI analytics agent searches Jentic for mobility data, loads the O2 Mobility schema, and pulls origin-destination counts to answer questions like 'how many people travelled from Brno to Prague last Friday?'. Jentic returns the validated operation and request schema so the agent can call the sandbox endpoint without parsing the swagger by hand. The agent runs the call, receives anonymised counts, and writes a short narrative answer.

Example prompt: Use Jentic to search 'transit between Czech residential units', load the GET `/transit/{from}/{to}` schema, and execute it with from=Brno-stred, to=Praha-Vinohrady for last Friday

## 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 of people travelling between two basic residential units
- **Info** — Application and dataset version metadata

## Why Jentic

- **Setup:** Wiring the O2 Mobility API by hand means targeting the developer.o2.cz sandbox host, handling any production-access step yourself, and building 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 'origin-destination counts in the Czech Republic', 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 data programme - adds age and gender breakdowns at a location
- **HERE Maps APIs** — Global mobility, routing, and traffic data from HERE - broader coverage 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 OpenAPI spec for the sandbox base URL declares no security schemes, so calls to `/transit/{from}/{to}` and /info on the sandbox host go through unauthenticated. Production use of the Liberty Developer programme requires a developer account; if you wire the API up via Jentic, any keys you obtain are stored in your Jentic One instance and injected at execution time so they never enter the agent's prompt context.

### Can I get counts of people travelling between two specific Czech locations with the O2 Mobility API?

Yes. Call GET `/transit/{from}/{to}` with the basic residential unit (ZSJ) codes for origin and destination, plus the time range parameters from the spec. The response contains anonymised aggregated counts derived from O2 Czech Republic mobile signalling, not individual trip records.

### Does the O2 Mobility API expose individual user locations?

No. The API only returns time-aggregated counts of people moving between residential units. There are no endpoints for live position, individual identifiers, or device-level traces, which keeps the dataset within Czech privacy expectations.

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

The OpenAPI spec does not document specific rate limits for the sandbox base URL. Treat the sandbox as best-effort and contact libertyapi@o2.cz for production quotas. Through Jentic, you can throttle calls in the agent loop to avoid bursts.

### How do I pull a Czech origin-destination matrix with the Mobility API through Jentic?

Install the Python SDK with pip install jentic, then run a search for 'transit between Czech residential units', load the GET `/transit/{from}/{to}` operation, and execute it with the ZSJ codes and time window. Jentic returns the JSON payload of aggregated counts so the agent can rank origins or destinations directly.

### How do I check which dataset version the API is serving?

Call GET /info. The endpoint returns application and data version strings so downstream pipelines can pin a known dataset and detect when the underlying mobility extract has been refreshed.

### 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, and the O2 Mobility API only exposes read-only GETs. You can allow just the transit-count operation, GET `/transit/{from}/{to}`, and the version-metadata operation, GET /info, so the agent can retrieve anonymised origin-destination counts and nothing else. Any operation you do not grant stays off limits, and any production access key is injected only at execution time so it never reaches the agent's prompt.