Playtomic APIplaytomic.com ↗
Search Playtomic sports clubs, fetch court details, check real-time slot availability, and calculate utilization across up to 7 days with 4 endpoints.
What is the Playtomic API?
The Playtomic API gives developers access to 4 endpoints covering sports club search, court details, slot availability, and multi-day court utilization. Use search_tenants to find padel and tennis clubs by name or location, then feed the returned tenant_id into get_court_availability to retrieve bookable time slots with start times, durations, and prices for any given date.
curl -X GET 'https://api.parse.bot/scraper/054f962f-b315-46ee-9242-29fd5442132f/search_tenants?page=0&query=Madrid&per_page=10&sport_id=PADEL' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace playtomic-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.playtomic_api import Playtomic, Sport, TenantNotFound
playtomic = Playtomic()
# Search for padel clubs in Madrid
for tenant in playtomic.tenants.search(query="Madrid", sport_id=Sport.PADEL, limit=3):
print(tenant.tenant_id, tenant.tenant_name, tenant.address.city)
# Get detailed info for a specific club
club = playtomic.tenants.get(tenant_id="02554cdf-4d4c-4a56-a6d1-088a0069195c")
print(club.tenant_name, club.opening_hours)
for court in club.resources:
print(court.name, court.properties.resource_type, court.properties.resource_size)
# Check court availability for that club
for avail in club.availability.list(sport_id=Sport.PADEL, date="2026-06-12"):
print(avail.resource_id, avail.start_date)
for slot in avail.slots:
print(slot.start_time, slot.duration, slot.price)
# Fetch utilization records
for record in playtomic.utilisationrecords.fetch(query="Madrid Central", sport_id=Sport.PADEL, days=1, limit=10):
print(record.court_name, record.date, record.time_slot, record.status)
Search for sports clubs/tenants by name. Returns a paginated list of matching clubs with their addresses, resources (courts), and opening hours. Paginates via zero-based page index.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (0-indexed) |
| queryrequired | string | Search query for club name (e.g. 'Madrid', 'City Tennis Club') |
| per_page | integer | Results per page |
| sport_id | string | Sport filter. |
{
"type": "object",
"fields": {
"items": "array of tenant objects with tenant_id, tenant_name, address, resources, and opening_hours"
},
"sample": {
"data": {
"items": [
{
"address": {
"city": "Madrid",
"street": "Calle de Boyer, 20 y 28",
"timezone": "Europe/Madrid",
"coordinate": {
"lat": 40.4039222,
"lon": -3.5879586
},
"postal_code": "28052",
"country_code": "ES"
},
"resources": [
{
"name": "Central Paquito Navarro",
"sport_id": "PADEL",
"properties": {
"resource_size": "double",
"resource_type": "indoor"
},
"resource_id": "1929feb7-9954-40d2-be07-acc641540c5e"
}
],
"tenant_id": "02554cdf-4d4c-4a56-a6d1-088a0069195c",
"tenant_name": "Madrid Central Pádel",
"opening_hours": {
"MONDAY": {
"closing_time": "00:00",
"opening_time": "07:00"
}
}
}
]
},
"status": "success"
}
}About the Playtomic API
Club Search and Details
The search_tenants endpoint accepts a query string and optional sport_id filter (PADEL or TENNIS) and returns an array of tenant objects — each with tenant_id, tenant_name, address data, a list of resources (courts), and opening hours. Results are paginated via zero-indexed page and per_page parameters. Once you have a tenant_id, get_tenant returns the full club profile including booking_settings and a complete resource list, and signals stale_input with kind: 'input_not_found' when the ID does not correspond to an existing club.
Court Availability
The get_court_availability endpoint takes a tenant_id, an optional date in YYYY-MM-DD format (defaults to today UTC if omitted), and an optional duration in minutes. It returns an array grouped by resource_id, with each entry containing a start_date and a slots array. Every slot includes start_time, duration, and price. Note that the upstream source returns all duration variants per slot — 60, 90, 120 minutes and others — regardless of the duration parameter value, so your application should filter the slots array client-side.
Utilization Analysis
The fetch_utilisation endpoint takes a club query string, an optional sport_id, and a days integer from 1 to 7. It resolves the club, iterates over courts and dates, and returns one record per court per 30-minute time slot. Each record exposes club_name, court_name, court_environment, court_type, date, weekday, time_slot, and an availability status field. This makes it straightforward to build occupancy heatmaps or capacity reports without stitching together multiple calls yourself.
The Playtomic API is a managed, monitored endpoint for playtomic.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when playtomic.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official playtomic.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Find all padel clubs within a city and display their addresses and opening hours to end users
- Check real-time available booking slots and prices for a specific court on a given date
- Build a court occupancy heatmap using 30-minute utilization increments from
fetch_utilisation - Compare booking settings across multiple clubs retrieved via
get_tenant - Aggregate weekly availability data to identify peak and off-peak hours for a club
- Filter tennis-only clubs using the
sport_idparameter across search and availability endpoints - Monitor court supply at a venue over a 7-day window for capacity planning
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Playtomic have an official public developer API?+
What does `get_court_availability` actually return, and does the `duration` filter work server-side?+
resource_id, with each slot carrying start_time, duration, and price. The duration parameter does not filter the response server-side — all duration variants (e.g. 60, 90, 120 minutes) are returned per slot regardless of the value passed. Filter the slots array in your own code if you only want a specific duration.Does the API cover booking creation or cancellation?+
Are sports other than padel and tennis supported in the `sport_id` filter?+
sport_id parameter currently accepts only PADEL and TENNIS. Other sports that Playtomic may list on their platform are not filterable via this parameter. You can fork the API on Parse and revise it to add support for additional sport IDs if those values become available.How far ahead can availability data be fetched, and is historical data accessible?+
get_court_availability defaults to today (UTC) when no date is provided and accepts any future date in YYYY-MM-DD format. The API returns whatever the source makes available for that date; there is no guaranteed booking horizon. Historical slot data for past dates is not exposed by the current endpoints.