Data & Location APIs

APIs for managing places, availability, bookings, and geographic data.

Places API

Manage and search for charging and parking locations.

List Places

Get all places for your tenant.

Endpoint: GET /api/v1/places

Query Parameters:

skip - Pagination offset (default: 0)
limit - Results per page (1-1000, default: 100)

Response:

[
  {
    "rollyy_id": "place_001",
    "name": "Downtown Charging Hub",
    "address": "123 Main St",
    "city": "San Francisco",
    "country": "US",
    "location": {
      "type": "Point",
      "coordinates": [-122.4194, 37.7749]
    },
    "place_type": "charging_station"
  }
]

Search Places by Location

Find places near a geographic coordinate.

Endpoint: GET /api/v1/places/search

Query Parameters:

lat - Latitude (-90 to 90)
lng - Longitude (-180 to 180)
radius_meters - Search radius (1-50000, default: 1000)
skip - Pagination offset
limit - Results per page

Example:

GET /api/v1/places/search?lat=37.7749&lng=-122.4194&radius_meters=5000

Response:

[
  {
    "rollyy_id": "place_001",
    "name": "Downtown Charging Hub",
    "address": "123 Main St",
    "distance_meters": 450,
    "location": {
      "type": "Point",
      "coordinates": [-122.4194, 37.7749]
    }
  }
]

Get Place by ID

Get detailed information about a specific place.

Endpoint: GET /api/v1/places/{place_id}

Response:

{
  "rollyy_id": "place_001",
  "name": "Downtown Charging Hub",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94102",
  "country": "US",
  "location": {
    "type": "Point",
    "coordinates": [-122.4194, 37.7749]
  },
  "place_type": "charging_station",
  "amenities": ["wifi", "restroom", "cafe"],
  "operating_hours": {
    "monday": "00:00-23:59",
    "tuesday": "00:00-23:59"
  }
}

Availability API

Real-time availability status for charging and parking assets.

Get Availability

Query current availability status using materialized views for performance.

Endpoint: GET /api/v1/availability

Query Parameters:

asset_id - Filter by specific asset
asset_type - Filter by type (charging or parking)
status - Filter by status (available, occupied, reserved, offline)
skip - Pagination offset
limit - Results per page

Example:

GET /api/v1/availability?asset_type=charging&status=available&limit=50

Response:

[
  {
    "asset_id": "charger_001",
    "asset_type": "charging",
    "status": "available",
    "last_updated": "2026-02-07T15:30:00Z",
    "connector_type": "CCS",
    "max_power_kw": 150,
    "current_power_kw": 0
  },
  {
    "asset_id": "charger_002",
    "asset_type": "charging",
    "status": "occupied",
    "last_updated": "2026-02-07T15:28:00Z",
    "connector_type": "CHAdeMO",
    "max_power_kw": 50,
    "current_power_kw": 48.5,
    "estimated_available_at": "2026-02-07T16:15:00Z"
  }
]

Bookings API

Reservation system for charging stations and parking spots.

Create Booking

Reserve a charging station or parking spot.

Endpoint: POST /api/v1/bookings

Request:

{
  "asset_id": "charger_001",
  "asset_type": "charging",
  "user_id": "user_123",
  "start_time": "2026-02-07T16:00:00Z",
  "end_time": "2026-02-07T17:00:00Z"
}

Response (201 Created):

{
  "rollyy_id": "booking_abc123",
  "asset_id": "charger_001",
  "asset_type": "charging",
  "user_id": "user_123",
  "start_time": "2026-02-07T16:00:00Z",
  "end_time": "2026-02-07T17:00:00Z",
  "status": "pending",
  "created_at": "2026-02-07T15:30:00Z"
}

Get Booking

Retrieve booking details by ID.

Endpoint: GET /api/v1/bookings/{booking_id}

Response:

{
  "rollyy_id": "booking_abc123",
  "asset_id": "charger_001",
  "asset_type": "charging",
  "user_id": "user_123",
  "start_time": "2026-02-07T16:00:00Z",
  "end_time": "2026-02-07T17:00:00Z",
  "status": "confirmed",
  "created_at": "2026-02-07T15:30:00Z",
  "confirmed_at": "2026-02-07T15:30:15Z"
}

List Bookings

Get bookings with optional filters.

Endpoint: GET /api/v1/bookings

Query Parameters:

user_id - Filter by user
status - Filter by status (pending, confirmed, active, completed, cancelled)

Response:

[
  {
    "rollyy_id": "booking_abc123",
    "asset_id": "charger_001",
    "user_id": "user_123",
    "start_time": "2026-02-07T16:00:00Z",
    "end_time": "2026-02-07T17:00:00Z",
    "status": "confirmed"
  }
]

Charging Assets API

Manage charging station inventory.

List Charging Assets

Get all charging stations.

Endpoint: GET /api/v1/charging-assets

Query Parameters:

place_id - Filter by location
network - Filter by charging network
skip - Pagination offset
limit - Results per page

Response:

[
  {
    "rollyy_id": "charger_001",
    "place_id": "place_001",
    "network": "ChargePoint",
    "connector_type": "CCS",
    "max_power_kw": 150,
    "status": "operational",
    "location": {
      "type": "Point",
      "coordinates": [-122.4194, 37.7749]
    }
  }
]

Get Charging Asset

Get details of a specific charging station.

Endpoint: GET /api/v1/charging-assets/{asset_id}

Response:

{
  "rollyy_id": "charger_001",
  "place_id": "place_001",
  "network": "ChargePoint",
  "connector_type": "CCS",
  "max_power_kw": 150,
  "voltage": 800,
  "current_max_a": 200,
  "status": "operational",
  "pricing": {
    "per_kwh": 0.35,
    "per_minute": 0.10,
    "currency": "USD"
  }
}

Parking Assets API

Manage parking spot inventory.

List Parking Assets

Get all parking spots.

Endpoint: GET /api/v1/parking-assets

Query Parameters:

place_id - Filter by location
skip - Pagination offset
limit - Results per page

Response:

[
  {
    "rollyy_id": "parking_001",
    "place_id": "place_001",
    "spot_number": "A-12",
    "spot_type": "standard",
    "ev_charging": true,
    "status": "available"
  }
]

Charging Sessions API

Track active and historical charging sessions.

Get Session Status

Get real-time status of a charging session.

Endpoint: GET /api/v1/charging-sessions/{session_id}

Response:

{
  "session_id": "session_abc123",
  "asset_id": "charger_001",
  "user_id": "user_123",
  "start_time": "2026-02-07T15:00:00Z",
  "status": "active",
  "energy_delivered_kwh": 25.5,
  "current_power_kw": 48.0,
  "duration_minutes": 32,
  "cost_usd": 8.93
}

European Data API

Access European parking and charging data from multiple sources.

Search European Locations

Find parking and charging locations in Europe.

Endpoint: GET /api/v1/european-data/search

Query Parameters:

lat - Latitude
lng - Longitude
radius_km - Search radius in kilometers
type - Filter by type (parking, charging, or both)

Response:

{
  "parking": [
    {
      "id": "park_eu_001",
      "name": "Central Parking",
      "address": "Hauptstraße 1, Berlin",
      "capacity": 200,
      "available_spots": 45,
      "location": {
        "lat": 52.520008,
        "lng": 13.404954
      }
    }
  ],
  "charging": [
    {
      "id": "charge_eu_001",
      "name": "Berlin Fast Charge",
      "connector_types": ["CCS", "CHAdeMO"],
      "max_power_kw": 150,
      "available": true
    }
  ]
}

Worldwide Data API

Global parking and charging data aggregation.

Search Worldwide

Search for parking and charging globally using Google Places API integration.

Endpoint: GET /api/v1/worldwide-data/search

Query Parameters:

lat - Latitude
lng - Longitude
radius_km - Search radius
type - parking, charging, or both

Response:

{
  "parking": [
    {
      "place_id": "ChIJ...",
      "name": "Public Parking Garage",
      "address": "123 Main St, San Francisco, CA",
      "location": {
        "lat": 37.7749,
        "lng": -122.4194
      },
      "rating": 4.2,
      "user_ratings_total": 156
    }
  ],
  "charging": [
    {
      "place_id": "ChIJ...",
      "name": "Tesla Supercharger",
      "address": "456 Market St, San Francisco, CA",
      "location": {
        "lat": 37.7849,
        "lng": -122.4094
      }
    }
  ]
}

Error Responses

All endpoints return errors in this format:

{
  "detail": "Error description"
}

Common HTTP Status Codes

Status	Description
`200`	Success
`201`	Created
`400`	Bad Request
`401`	Unauthorized
`404`	Not Found
`422`	Validation Error
`500`	Internal Server Error

Data & Location APIs

Places API​

List Places​

Search Places by Location​

Get Place by ID​

Availability API​

Get Availability​

Bookings API​

Create Booking​

Get Booking​

List Bookings​

Charging Assets API​

List Charging Assets​

Get Charging Asset​

Parking Assets API​

List Parking Assets​

Charging Sessions API​

Get Session Status​

European Data API​

Search European Locations​

Worldwide Data API​

Search Worldwide​

Error Responses​

Common HTTP Status Codes​

Places API

List Places

Search Places by Location

Get Place by ID

Availability API

Get Availability

Bookings API

Create Booking

Get Booking

List Bookings

Charging Assets API

List Charging Assets

Get Charging Asset

Parking Assets API

List Parking Assets

Charging Sessions API

Get Session Status

European Data API

Search European Locations

Worldwide Data API

Search Worldwide

Error Responses

Common HTTP Status Codes