Tutorial: GBFS Bikeshare

Transport

Data source: GBFS (General Bikeshare Feed Specification) — city operators

Overview

GBFS Bikeshare wraps GBFS (General Bikeshare Feed Specification) — city operators, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-gbfs": {
      "url": "https://context.gnist.ai/mcp/gbfs/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`list_systems`

List available bikeshare/scooter systems from the catalog. Returns a curated list of 30+ major city bike/scooter sharing systems worldwide that publish GBFS (General Bikeshare Feed Specification) data. Filter by country or search by name/city/operator. Use this first to discover system_ids, then call get_stations or get_system_info with the chosen system_id. Args: country: 2-letter ISO country code filter (e.g. "NO" for Norway). query: Search text matching name, city, or operator name. limit: Maximum systems to return (1-100). Returns: List of systems with system_id, name, city, country, operator.

Parameter	Type	Required	Description
`country`	any	optional	ISO 3166-1 alpha-2 country code to filter systems (e.g. "NO", "US", "GB", "FR").
`query`	any	optional	Text search across system name, city, and operator (e.g. 'Oslo', 'Lime', 'Citi Bike').
`limit`	integer	optional	Maximum systems to return (1-100, default 50). (default: `50`)

curl -X POST "https://context.gnist.ai/mcp/gbfs/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_systems", "arguments": {"country": "NO"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbfs/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'country': 'NO'}, 'name': 'list_systems'}},
)
print(resp.json())

`get_system_info`

Get metadata for a specific bikeshare system. Fetches the system_information.json GBFS feed for the system and returns operator details, timezone, contact info, and available feeds. Args: system_id: System identifier from list_systems (e.g. "oslobysykkel"). Returns: System metadata including name, operator, URL, timezone, and a list of available GBFS feed names.

Parameter	Type	Required	Description
`system_id`	string	required	System identifier from list_systems (e.g. "oslobysykkel", "lyft_nyc", "divvy").

curl -X POST "https://context.gnist.ai/mcp/gbfs/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_system_info", "arguments": {"system_id": "oslobysykkel"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbfs/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'system_id': 'oslobysykkel'},
            'name': 'get_system_info'}},
)
print(resp.json())

`get_stations`

Get stations with real-time bike/dock availability for a bikeshare system. Merges static station info (name, location, capacity) with live status (bikes available, docks available, vehicle types). Returns all stations or filters by name/address text search. Use get_station_status for detailed info on a single station. Args: system_id: System identifier (e.g. "oslobysykkel"). query: Optional text filter on station name or address. limit: Maximum stations to return (1-100, default 50). Returns: Stations with name, lat/lon, capacity, bikes_available, docks_available, is_renting, is_returning, last_reported timestamp.

Parameter	Type	Required	Description
`system_id`	string	required	System identifier from list_systems (e.g. "oslobysykkel", "lyft_nyc").
`query`	any	optional	Text filter on station name or address (e.g. 'Central Station', 'Main St').
`limit`	integer	optional	Maximum stations to return (1-100, default 50). (default: `50`)

curl -X POST "https://context.gnist.ai/mcp/gbfs/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_stations", "arguments": {"system_id": "oslobysykkel"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbfs/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'system_id': 'oslobysykkel'}, 'name': 'get_stations'}},
)
print(resp.json())

`get_station_status`

Get real-time availability for a specific bikeshare station. Returns live data including bikes available, docks available, operational status (is_renting, is_returning), and last update timestamp. Also includes static info (name, address, coordinates, capacity). Args: system_id: System identifier (e.g. "oslobysykkel"). station_id: Station identifier from get_stations results. Returns: Station details with name, address, lat/lon, capacity, bikes_available, docks_available, is_installed, is_renting, is_returning, last_reported.

Parameter	Type	Required	Description
`system_id`	string	required	System identifier from list_systems (e.g. "oslobysykkel", "lyft_nyc").
`station_id`	string	required	Station identifier from get_stations results.

curl -X POST "https://context.gnist.ai/mcp/gbfs/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_station_status", "arguments": {"system_id": "oslobysykkel", "station_id": "12345"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbfs/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'station_id': '12345', 'system_id': 'oslobysykkel'},
            'name': 'get_station_status'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/gbfs/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/gbfs/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use list_systems to find items, then get_system_info to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does GBFS Bikeshare provide?

Real-time bike and scooter sharing availability across 30+ city systems worldwide — stations, bikes available, docks, and system info via the open GBFS standard. It exposes 5 tools: list_systems, get_system_info, get_stations, get_station_status, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the GBFS Bikeshare API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.