canonical: https://jentic.com/apis/jcdecaux.com/jcdecaux

# JCDecaux Bike API

Jentic publishes the only available OpenAPI specification for JCDecaux Bike API, keeping it validated and agent-ready. The JCDecaux Bike API exposes real-time data for the JCDecaux self-service bicycle network, covering contracts (cities and regions), individual stations, and live availability of bikes and stands. Each station response includes geographic coordinates, total stand count, available bikes, available empty stands, banking-enabled status, and a last-update timestamp, so applications can render maps, plan routes, or alert users when a station is full or empty. Authentication uses a single apiKey query parameter issued from the JCDecaux developer portal.

## For AI agents

Read live JCDecaux bike-share data: list contracts (cities), list all stations for a contract, and fetch real-time availability for any station by number.

## Scope

Does not handle bike rentals, payment processing, user accounts, or trip history - use for read-only, real-time bike-share station availability only.

## Capabilities

- List every JCDecaux bike-share contract (city/region) available worldwide via /contracts
- Retrieve real-time bike and stand availability for all stations in a contract via /stations
- Fetch a single station's live status, coordinates, and stand counts by station number
- Filter station listings by contract name to narrow results to one city
- Detect whether a station has a banking (payment) terminal via the banking flag on Station responses
- Identify currently OPEN versus CLOSED stations for routing logic

## Use cases

### City Bike Availability Map

Power a public-facing map that shows every JCDecaux station in a city with live bike and empty-stand counts. The /stations endpoint returns coordinates, status, and stand totals in one call, refreshed roughly every minute by JCDecaux. A typical city covers 100-1,500 stations, so a single polled request keeps the map current without any per-station calls.

Example prompt: Call GET /stations with contract=Paris and return only stations where available_bikes > 0 sorted by distance from a given lat/long.

### Trip Planning and Last-Mile Routing

A journey-planner can call `/stations/{station_number}` immediately before suggesting a station to confirm there are bikes to pick up at the origin and empty stands to drop at the destination. Because availability changes minute-to-minute, this just-in-time check prevents routing users to stations that have just emptied or filled.

Example prompt: Given an origin and destination station number, call GET `/stations/{station_number}` for both and return a route only if origin has available_bikes >= 1 and destination has available_bike_stands >= 1.

### Coverage and Expansion Analytics

Researchers and city planners can query /contracts to enumerate every JCDecaux deployment globally, then drill into /stations per contract to compute fleet size, density, and banking-station ratios. This is useful for benchmarking shared-mobility coverage across cities without scraping public dashboards.

Example prompt: Call GET /contracts, then for each contract name call GET /stations?contract={name} and report the total station count and the percentage with banking=true.

### AI Agent Integration via Jentic

An AI travel or commute assistant uses Jentic to discover JCDecaux operations by intent. The agent calls Jentic search with 'find available bike stations' and Jentic returns the JCDecaux operation schema with the apiKey parameter and contract filter, so the agent can execute the call without reading developer-portal docs. The API key stays in your Jentic One instance.

Example prompt: Search Jentic for 'find nearest bike share station with available bikes', load the JCDecaux getStations schema, and execute it with contract=Dublin to return the top 5 stations by available_bikes.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/contracts` | List all JCDecaux bike-share contracts (cities) |
| GET | `/stations` | List all stations or filter by contract |
| GET | `/stations/{station_number}` | Get live status for a single station |

## Key resources

- **Contracts** — List every city/region operating a JCDecaux bike-share contract.
- **Stations** — List or filter all bike-share stations and read individual station status, coordinates, and live bike/stand counts.

## Why Jentic

- **Setup:** Wiring the JCDecaux Bike API by hand means appending your apiKey to the query string on every call and polling station availability yourself. Through Jentic you install once, import the JCDecaux Bike API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** The JCDecaux Bike API is read-only station availability, so scope by operation: allow the agent only the read operations it needs, such as listing contracts and stations or reading one station. You pick the allowed set, so it stays within real-time availability lookup.
- **Credential handling:** Your JCDecaux API key is stored once, encrypted, by your own Jentic One instance and injected into the apiKey query parameter at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find available bike-share stations', and Jentic returns the matching JCDecaux station operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Transit App API** — Multi-modal transit data (bus, rail, bike share) versus JCDecaux's single-operator bike feed
- **Transport for London Unified API** — London-specific transit data including TfL Santander Cycles, useful alongside JCDecaux for cities outside the JCDecaux network

## FAQ

### Why is there no official OpenAPI spec for JCDecaux Bike API?

JCDecaux does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call JCDecaux Bike API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the JCDecaux Bike API use?

The API uses a single apiKey passed as a query parameter named apiKey on every request. Keys are issued from the JCDecaux developer portal at developer.jcdecaux.com. When called through Jentic, the key is held in your Jentic One instance and injected at execution time, so it never enters the agent's prompt context.

### Can I get live bike counts for a specific station with the JCDecaux Bike API?

Yes. Call GET `/stations/{station_number}` with the station_number path parameter and a contract query parameter to get the station's available_bikes, available_bike_stands, status (OPEN/CLOSED), and last_update timestamp. JCDecaux refreshes these counts roughly once per minute.

### What are the rate limits for the JCDecaux Bike API?

JCDecaux does not publish a fixed rate limit in the spec, but the developer portal asks integrators to cache responses and avoid polling individual stations more than once per minute. For city-wide updates, prefer one GET /stations?contract=... call over many per-station calls.

### How do I find every available JCDecaux bike-share city through Jentic?

Run pip install jentic, then search for 'list JCDecaux contracts'. Jentic returns the getContracts operation; load it and execute with no parameters beyond the apiKey to receive the full list of contract names, commercial names, and country codes.

### Is the JCDecaux Bike API free?

Yes - JCDecaux issues free developer keys for the open-data Bike API. Higher-volume or commercial use cases should contact JCDecaux directly through developer.jcdecaux.com.

### Can I limit what my agent is allowed to do with the JCDecaux Bike API?

Yes. Because you run Jentic One yourself, your own rules decide which JCDecaux operations and credentials the agent may use. Since this API is read-only station data, you can scope the agent to just the operations it needs, such as listing contracts, listing stations, or reading a single station's live availability, and withhold the rest. Your JCDecaux API key stays in your own instance and is injected only when an allowed operation runs.