Vélib' Métropole Getting Started: API Access (2026)

Getting started overview

Vélib' Métropole is a large-scale public bicycle-sharing system serving Paris and 55 surrounding municipalities. While the service itself is consumer-facing, offering Vélib' classique (green bikes) and Vélib' électrique (blue bikes) for rental, developers can access real-time data about station status, bike availability, and dock count. This data is not provided directly by Vélib' Métropole but is made available through the City of Paris Open Data platform, leveraging a data feed from JCDecaux, the system's operator. The API exposes information vital for applications that help users locate available bikes or plan their routes based on station occupancy.

To begin, you will register on the City of Paris Open Data platform to obtain API keys. While the Vélib' Métropole service involves various subscription models and pay-as-you-go options for bike usage, access to its public data API through the City of Paris Open Data platform is generally free. This page focuses on the technical steps to retrieve station data, not on the process of renting a Vélib' bike for personal use.

Here is a quick reference for the initial setup:

Create an account and get keys

To access the Vélib' Métropole real-time data, you must first register on the City of Paris Open Data platform. This platform serves as the central hub for various public datasets, including those related to Vélib' Métropole. Follow these steps to set up your access:

1. Navigate to the platform: Open your web browser and go to the City of Paris Open Data homepage.

2. Create an account: Look for a 'Register' or 'Sign Up' option, typically located in the top right corner of the page. You will need to provide an email address, create a password, and agree to the terms of service. Account creation typically involves email verification.

3. Locate the Vélib' dataset: Once logged in, use the search bar or browse the categories to find datasets related to Vélib' Métropole. The key dataset is usually provided by JCDecaux, which operates the Vélib' system. A direct link to relevant datasets can often be found by searching for "Vélib' JCDecaux" or navigating to JCDecaux Vélib' data on OpenData Paris.

4. Subscribe to the dataset/API: Some datasets on the platform require a subscription to access their API. If a subscription is necessary, you will typically find a 'Subscribe' or 'Get API Key' button on the dataset's dedicated page. Clicking this button will usually generate an API key or provide instructions on how to obtain one. This key is your credential for making authenticated requests.

5. Record your API Key: Once generated, copy your API key and store it securely. This key will need to be included as a parameter or header in your API requests to authenticate them. The specific method for including the key (e.g., ?apikey=YOUR_KEY in the URL or an Authorization header) will be detailed in the dataset's documentation on the Open Data platform.

The City of Paris Open Data platform typically follows RESTful API principles for data access. Familiarity with REST API concepts can be helpful for understanding how to interact with these endpoints effectively.

Your first request

After obtaining your API key from the City of Paris Open Data platform, you can make your first request to retrieve Vélib' station data. This example demonstrates how to fetch a list of stations and their current status using a common tool like cURL. The exact endpoint and parameter names may vary slightly; always refer to the specific dataset's documentation on the OpenData Paris platform for the most up-to-date information.

A typical endpoint for Vélib' station data might look like this (example only; check official docs for exact URL):

https://opendata.paris.fr/api/explore/v2.1/catalog/datasets/velib-disponibilite-en-temps-reel/records?apikey=YOUR_API_KEY&limit=10

In this example:

• https://opendata.paris.fr/api/explore/v2.1/catalog/datasets/velib-disponibilite-en-temps-reel/records is the base URL for the dataset.
• apikey=YOUR_API_KEY is where you replace YOUR_API_KEY with the key you obtained.
• limit=10 is an optional parameter to limit the number of records returned.

Using cURL (Command Line)

cURL is a command-line tool for making HTTP requests and is useful for quickly testing API endpoints. Replace YOUR_API_KEY with your actual key.

curl -X GET \
  "https://opendata.paris.fr/api/explore/v2.1/catalog/datasets/velib-disponibilite-en-temps-reel/records?apikey=YOUR_API_KEY&limit=5" \
  -H "Accept: application/json"

If successful, this command will return a JSON object containing an array of Vélib' station data. Each object in the array will represent a station and include details such as:

• stationcode: Unique identifier for the station.
• name: Name of the station.
• coordonnees_geo: Geographic coordinates (latitude, longitude).
• numbikesavailable: Number of classic bikes currently available.
• numdocksavailable: Number of empty docks available.
• capacity: Total capacity of the station.
• ebike: Number of electric bikes available (if provided by the dataset).
• mechanical: Number of mechanical bikes available (if provided by the dataset).
• duedate: Timestamp of the last update.

The structure of the JSON response will be defined by the specific dataset. The City of Paris Open Data platform typically provides schema documentation for each dataset. For processing JSON responses in various programming languages, developers can refer to resources like MDN Web Docs on JSON for parsing methods.

Using Python

For programmatic access, Python with the requests library is a common choice:

import requests
import json

api_key = "YOUR_API_KEY"
base_url = "https://opendata.paris.fr/api/explore/v2.1/catalog/datasets/velib-disponibilite-en-temps-reel/records"

params = {
    "apikey": api_key,
    "limit": 5
}

try:
    response = requests.get(base_url, params=params)
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
    data = response.json()
    print(json.dumps(data, indent=2))
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")

This Python script makes a GET request, handles potential HTTP errors, and prints the pretty-printed JSON response. Remember to install the requests library if you haven't already (pip install requests).

Common next steps

Once you have successfully made your first API call and received Vélib' station data, you can proceed with further development:

1. Parse and process data: Integrate the JSON response into your application. You will likely need to parse the data to extract specific fields like station name, coordinates, and bike availability for display or analysis. Consider data structures that efficiently store and retrieve this information.

2. Display on a map: A common use case for Vélib' data is to display station locations and their real-time status on a map. Libraries like Leaflet, Mapbox, or Google Maps API can be used to render this data dynamically. For example, the Google Maps JavaScript API provides methods for adding markers and info windows to display station details.

3. Implement data refreshing: Vélib' station data is dynamic. To provide up-to-date information, your application will need to periodically refresh the data by making new API calls. Consider appropriate refresh intervals to avoid excessive API requests while keeping data current (e.g., every 30 seconds to 1 minute).

4. Error handling and rate limits: Implement robust error handling for network issues, API errors (e.g., invalid API key, server errors), and empty responses. Be aware of any rate limits imposed by the City of Paris Open Data platform to prevent your application from being temporarily blocked. Consult the platform's documentation for specific rate limit policies.

5. Filtering and querying: Explore the available query parameters for the Vélib' dataset. The Open Data platform often supports filtering by geographical area, specific station codes, or other criteria. This allows you to retrieve only the data relevant to your application's needs, reducing bandwidth and processing overhead.

6. Build user interface: Develop a user interface (web, mobile, or desktop) that presents the Vélib' data in an intuitive and helpful way for users, such as showing nearest stations, filtering by bike type, or predicting availability.

Troubleshooting the first call

If your first API request to the Vélib' data endpoint doesn't return the expected results, consider these common troubleshooting steps:

• Check your API Key: Ensure that YOUR_API_KEY in the URL or header is correct and matches the key provided by the City of Paris Open Data platform. Typos are common. If you suspect an issue, try generating a new key on the platform.

• Verify the Endpoint URL: Double-check that the base URL for the API endpoint is exactly as specified in the dataset's documentation on the City of Paris Open Data platform. Endpoints can change, so always refer to the official source.

• Parameter Names: Confirm that all query parameters (e.g., apikey, limit) are spelled correctly and in the correct case. API parameters are often case-sensitive.

• Internet Connectivity: Ensure your development environment has an active internet connection and no firewall or proxy is blocking outgoing HTTP requests.

• HTTP Status Codes: Examine the HTTP status code returned by the API. Common codes include:

  • 200 OK: Request was successful.
  • 400 Bad Request: Often due to missing or malformed parameters.
  • 401 Unauthorized: Incorrect or missing API key.
  • 403 Forbidden: Your API key might not have permission for the requested resource, or you've hit a rate limit.
  • 404 Not Found: Incorrect endpoint URL.
  • 429 Too Many Requests: You have exceeded the API's rate limit. Wait before trying again.
  • 5xx Server Error: An issue on the API provider's side.

  In Python, response.raise_for_status() will automatically raise an exception for 4xx/5xx responses.

• Response Body: If an error occurs, the API often returns an error message in the response body (usually JSON). Read this message carefully as it typically provides specific details about what went wrong.

• Documentation Review: Re-read the API documentation for the specific Vélib' dataset on the City of Paris Open Data platform. There might be specific requirements or nuances you missed.

• Community Forums/Support: If you continue to face issues, check if the City of Paris Open Data platform has a forum or support contact where you can ask for assistance. Other developers might have encountered similar problems.