rec.us API

• Sport — a sport or activity (e.g. Tennis, Pickleball, Yoga). Referenced by sites, instructors, and sections.
• Region — a geographic area (e.g. "San Francisco Area", "East Bay"). Used to discover locations across multiple organizations.
• Organization — a municipal parks & rec department (e.g. "San Francisco Rec & Park"). Configures which features are enabled.
  • Location — a park or facility with bookable sites. Has address, hours, and a reservation window.
    • Site — a bookable unit within a location (court, field, room, picnic table, etc.). Has pricing and allowed durations. Some are walk-up only. Note: The API uses "site" in paths but many response keys use the legacy name courts/courtNumber.
  • Instructor — a coach who offers private lessons. Has sport-specific hourly rates and available time slots.
  • Section — a group class or lesson pack. Has a facilitator, capacity, and multiple sessions.
    • Session — an individual meeting within a section, with a specific date/time.
• Facility Rental — a site booking created via POST /v1/facility-rentals. Wraps a reservation and an order.
  • Reservation — the time slot hold on a site.
  • Order — the transactional record. Created with pending status and ~10 min expiration. Must be paid (even if $0) to finalize.
    • Payment — settles an order. Has a method type (e.g. free, cardOnline) and amount in cents.

Some list endpoints are paginated (default page size 25) — callers must iterate pages to get all results. Others return the full dataset in a single response.

Parameters

All paginated endpoints accept either of these equivalent param styles:

Both styles are interchangeable on every paginated endpoint. Page numbers are 1-indexed.

Response envelopes

The response shape is fixed per endpoint (does not depend on which param style you use). Two envelope styles exist:

data/meta envelope:

{
  "data": [ ... ],
  "meta": { "pg": { "num": 1, "size": 25, "totalResults": 49 } }
}

More pages exist while pg.num * pg.size < pg.totalResults.

results/total envelope:

{
  "results": [ ... ],
  "total": 157
}

More pages exist while page * pageSize < total. The response does not echo back the current page number.

Authenticated endpoints (marked with a lock icon) require a Firebase Auth ID token passed as a Bearer token.

Firebase project: rec-prod Firebase Web API key: AIzaSyCp6DCwnx-6GwkMyI2G1b8ixYs4AXZc-7s

Sign in with email/password

POST https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=AIzaSyCp6DCwnx-6GwkMyI2G1b8ixYs4AXZc-7s

Request body:

{
  "email": "user@example.com",
  "password": "password",
  "returnSecureToken": true
}

Response:

{
  "localId": "1N78WJBXjdU1avTCTx9z1JkFWMv1",
  "email": "user@example.com",
  "displayName": "",
  "idToken": "eyJhbGciOi...",
  "refreshToken": "AMf-vBx...",
  "expiresIn": "3600"
}

The idToken is used as the Bearer token for all authenticated API calls:

Authorization: Bearer {idToken}

Tokens expire after 1 hour. Use the refreshToken with the Firebase token refresh endpoint to obtain a new idToken.

Find Available Pickleball Sites

# 1. List organizations
curl -s 'https://api.rec.us/v1/organizations' | jq '.data[].slug'

# 2. Get org detail to find location IDs (in config.banners.pages)
curl -s 'https://api.rec.us/v1/organizations/san-francisco-rec-park' | jq '.config.banners.pages | keys[]'

# 3. Get location detail
curl -s 'https://api.rec.us/v1/locations/ad9e28e1-2d02-4fb5-b31d-b75f63841814' | jq '.location.name, .location.courts[].courtNumber'

# 4. Check schedule for available slots
curl -s 'https://api.rec.us/v1/locations/ad9e28e1-2d02-4fb5-b31d-b75f63841814/schedule?startDate=2026-03-01' | \
  jq '.dates["20260301"][] | select(.sports[].name == "Pickleball") | {court: .courtNumber, slots: [.schedule | to_entries[] | select(.value.referenceType == "RESERVABLE") | .key]}'

Find Available Tennis Instructors

# 1. List instructors with open lesson slots
curl -s 'https://api.rec.us/v1/instructors/cards/lessons?organizationSlug=san-francisco-rec-park' | \
  jq '.[] | {name: .fullName, sport: .sports[0].name, rate: .sports[0].hourlyRate, nextLesson: .lessons[0].reservationTimestampRange}'

# 2. Get full instructor profile
curl -s 'https://api.rec.us/v1/instructors/{instructorId}' | jq '{name: .user.firstName + " " + .user.lastName, bio: .longBio, locations: [.instructorLocations[].locationId]}'

Find Group Classes

# List all programs for SF Rec Park in the next 90 days
curl -s 'https://api.rec.us/v1/discovery/programmed?organizationId=17380e28-7e02-4b52-82c5-fab18557fd7a&startDate=2026-02-27&endDate=2026-05-27' | \
  jq '.[] | {name: .name, sport: .sportName, location: .locationName, spots: (.capacity - .participantCount), sessions: (.sessions | length)}'

Book a Free Site (Full Flow)

End-to-end example booking a free pickleball site at Granada Park.

# 1. Authenticate
TOKEN=$(curl -s -X POST \
  'https://identitytoolkit.googleapis.com/v1/accounts:signInWithPassword?key=AIzaSyCp6DCwnx-6GwkMyI2G1b8ixYs4AXZc-7s' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","password":"password","returnSecureToken":true}' \
  | jq -r '.idToken')

# 2. Find the location — search by region or org
#    Granada Park is in the San Francisco Area region
curl -s 'https://api.rec.us/v1/locations/availability?regionId=51cad8df-4985-4c09-ba5e-c7893f672c26' | \
  jq '.[] | select(.location.name == "Granada Park") | .location | {id, name, courts: [.courts[] | {id, court: .courtNumber, pricing: .config.pricing.default}]}'

# 3. Check the schedule for available pickleball slots on a specific date
LOCATION_ID="38a201f0-4fb1-4991-8e72-db8a9495319e"
curl -s "https://api.rec.us/v1/locations/$LOCATION_ID/schedule?startDate=2026-03-05" | \
  jq '.dates["20260305"][] | select(.sports[].name == "Pickleball") | {court: .courtNumber, slots: [.schedule | to_entries[] | select(.value.referenceType == "RESERVABLE") | .key]}'

# 4. Verify the site supports instant booking
SITE_ID="99b7129e-5ed4-4fd8-aba2-fee1683310bb"   # Site A (court)
curl -s "https://api.rec.us/v1/sites/$SITE_ID" \
  -H "Authorization: Bearer $TOKEN" | \
  jq '.data | {id, courtNumber, isInstantBookable, capacity}'

# 5. Create the reservation
ORDER_ID=$(curl -s -X POST 'https://api.rec.us/v1/facility-rentals' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"data\": {
      \"reservation\": {
        \"timestampRange\": \"[2026-03-05 13:00:00, 2026-03-05 14:00:00)\",
        \"locationId\": \"$LOCATION_ID\",
        \"courtIds\": [\"$SITE_ID\"]
      }
    }
  }" | jq -r '.data.order.id')

echo "Order created: $ORDER_ID"

# 6. Complete the order (required even for $0 reservations)
curl -s -X POST "https://api.rec.us/v1/orders/$ORDER_ID/pay" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":{"payments":[{"paymentMethodType":"free","amountCents":0}]}}' | \
  jq '.data | {status, settledAt}'

# 7. Verify — the slot should now show as RESERVATION
curl -s "https://api.rec.us/v1/locations/$LOCATION_ID/schedule?startDate=2026-03-05" | \
  jq '.dates["20260305"][] | select(.courtNumber == "A") | .schedule["13:00, 14:00"]'
# → { "referenceType": "RESERVATION", "referenceId": "..." }

Key points:

• After POST /v1/facility-rentals, the order is "pending" with a ~10 minute expiration. You must call POST /v1/orders/{orderId}/pay to finalize it.
• For free sites, use paymentMethodType: "free" with amountCents: 0.
• The timestampRange uses PostgreSQL range syntax: [start, end) — inclusive start, exclusive end.
• Times in timestampRange are in the location's local timezone (e.g. America/Los_Angeles).

Book a Paid Site (Full Flow)

Same as the free site flow above, but diverges at step 4 — the site has a fixed-slots booking policy, and payment requires a Stripe confirmation step.

# Steps 1-3 are the same as "Book a Free Site" (authenticate, find location, check schedule).

# 4. Get site detail — check booking policy and pricing
SITE_ID="040a5a1a-443a-4641-b079-ed7e650bd5ac"   # J.P. Murphy site "Court 3"
curl -s "https://api.rec.us/v1/sites/$SITE_ID" \
  -H "Authorization: Bearer $TOKEN" | \
  jq '.data | {id, courtNumber, isInstantBookable, noReservationText,
    pricing: .config.pricing.default,
    bookingPolicy: .config.bookingPolicies[0].type,
    fixedSlots: [.config.bookingPolicies[0].slots[] | select(.dayOfWeek == 7) | {start: .startTimeLocal, end: .endTimeLocal}]}'
# → bookingPolicy: "fixed-slots", fixedSlots: [{start: "16:30:00", end: "18:00:00"}, ...]
# With fixed-slots, your timestampRange MUST match a slot exactly.

# 5. Create the reservation (timestampRange matches the fixed slot 16:30-18:00)
LOCATION_ID="7a8ef25a-dc20-4046-8aab-7212a9a41d20"
RESULT=$(curl -s -X POST 'https://api.rec.us/v1/facility-rentals' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"data\": {
      \"reservation\": {
        \"timestampRange\": \"[2026-03-01 16:30:00, 2026-03-01 18:00:00)\",
        \"locationId\": \"$LOCATION_ID\",
        \"courtIds\": [\"$SITE_ID\"]
      }
    }
  }")
ORDER_ID=$(echo "$RESULT" | jq -r '.data.order.id')
ITEM_ID=$(echo "$RESULT" | jq -r '.data.order.items[0].id')
TOTAL=$(echo "$RESULT" | jq -r '.data.order.total')
echo "Order: $ORDER_ID, Item: $ITEM_ID, Total: $TOTAL cents"
# → Total: 750 (= $7.50 for 1.5 hours at $5/hour)

# 6. Look up saved payment methods
USER_ID=$(echo "$RESULT" | jq -r '.data.order.customer.id')
ORG_ID=$(echo "$RESULT" | jq -r '.data.order.organization.id')
curl -s -X POST "https://api.rec.us/v1/users/$USER_ID/payment-method-setup" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"data\":{\"organizationId\":\"$ORG_ID\"}}" | \
  jq '.data.paymentMethods[] | {id, brand: .card.brand, last4: .card.last4}'
# → { "id": "pm_1Sygm4CMyY4UUjhBOhNeoApv", "brand": "visa", "last4": "7510" }

# 7. Submit payment (use "ACH" type — "cardOnline" is rejected by the API)
PAY_RESULT=$(curl -s -X POST "https://api.rec.us/v1/orders/$ORDER_ID/pay" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"data\":{\"payments\":[{\"paymentMethodType\":\"ACH\",\"amountCents\":$TOTAL}]}}")

# Extract Stripe PaymentIntent details from the response
PI_ID=$(echo "$PAY_RESULT" | jq -r '.included.payments[0].gatewayData.paymentIntentId')
CLIENT_SECRET=$(echo "$PAY_RESULT" | jq -r '.included.payments[0].gatewayData.clientSecret')
echo "PaymentIntent: $PI_ID"

# 8. Confirm the PaymentIntent with Stripe using the saved card
PM_ID="pm_1Sygm4CMyY4UUjhBOhNeoApv"  # from step 6
STRIPE_PK="pk_live_51MPUx4CMyY4UUjhBlgalg5uPiGdXHOWbOTEOioIXfReEeAuLviTRXhdTGvZtTnYtDm2eZonv8buTf73YKIzJHV4i00YikF7WiB"
curl -s -X POST "https://api.stripe.com/v1/payment_intents/$PI_ID/confirm" \
  -u "$STRIPE_PK:" \
  -d "payment_method=$PM_ID" \
  -d "client_secret=$CLIENT_SECRET" | \
  jq '{status, amount, currency}'
# → { "status": "succeeded", "amount": 750, "currency": "usd" }

# 9. Verify — order should show totalAmountRemaining: 0
curl -s "https://api.rec.us/v1/orders/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN" | \
  jq '.order | {status, total, totalAmountRemaining}'

Key differences from the free site flow:

• Fixed-slots sites require timestampRange to exactly match a pre-defined slot boundary (check config.bookingPolicies). Using a custom duration like [16:30, 17:30) will fail with "The reservation violates the site's booking policy".
• Card payment is a two-step process: (1) call /pay with paymentMethodType: "ACH" to create a Stripe PaymentIntent, then (2) confirm it via the Stripe API with a saved payment_method ID.
• The Stripe publishable key authenticates the /confirm call (passed as HTTP basic auth username with empty password).
• After Stripe confirmation, rec.us is notified via webhook and the order settles automatically.
• Daily booking limits exist per location/date (e.g. 1 reservation per day). Expired unpaid orders may still count against the limit temporarily. The error is E_INELIGIBLE_SITE_BOOKING with a message like "Daily booking limit of 1 reached for March 1, 2026".

Availability & Schedule — Endpoint Comparison

Four endpoints return time slot / availability data. They overlap significantly but each has unique fields.

Computing per-slot durations client-side

GET /v1/sites/{id}/availability returns availableDurationsMinutes per time slot, but requires one request per site — impractical for multi-site views. Both GET /v1/locations/{id} and GET /v1/locations/availability return enough data to compute equivalent durations client-side (this is what the rec.us frontend does for court reservations on the location detail page).

Each site (in courts[]) provides three relevant fields:

• availableSlots — bookable start times as "YYYY-MM-DD HH:MM:SS" strings
• allowedReservationDurations.minutes — e.g. [30, 60, 90]
• config.bookingPolicies[] — optional; when present with type: "fixed-slots" and isActive: true, the site uses pre-defined time blocks

Fixed-slot sites (active bookingPolicies with type: "fixed-slots"):

The bookingPolicies[].slots array defines the valid time blocks per day of week (dayOfWeek 1=Mon…7=Sun). Each slot has startTimeLocal and endTimeLocal. For each block whose startTimeLocal (truncated to HH:MM) appears in availableSlots on a matching day-of-week, the only available duration is endTimeLocal - startTimeLocal. The allowedReservationDurations field is ignored — it contains a stale superset.

Note: availableSlots for fixed-slot sites includes every 30-minute tick within the open range (e.g. 07:30, 08:00, 08:30 for a 07:30–09:00 block), but only the block start times are valid booking starts.

Flexible-booking sites (no active bookingPolicies, or isActive: false):

For each start time in availableSlots, check which durations from allowedReservationDurations.minutes are feasible by verifying that all consecutive 30-minute sub-slots exist:

for each duration in allowedReservationDurations.minutes (ascending):
    feasible = true
    for offset in 0, 30, 60, ... (duration - 30):
        if (startTime + offset) not in availableSlots for that date:
            feasible = false; break
    if feasible: include duration

For example, with allowedReservationDurations: [30, 60, 90] and availableSlots containing 17:00, 17:30, 18:00 but not 18:30:

• At 17:00: [30, 60, 90] (17:00, 17:30, 18:00 all present)
• At 17:30: [30, 60] (17:30, 18:00 present; 18:30 missing)
• At 18:00: [30] (18:00 present; 18:30 missing)

This computation produces results identical to GET /v1/sites/{id}/availability.

Sport and activity types

Geographic regions

Municipal parks & rec departments

Parks and facilities with bookable sites

Private lesson instructors

Program and group class discovery

Bookable units (courts, fields, rooms, picnic tables, etc.)

User profiles and account management

Site reservation creation

Order management and checkout