WaitTime Intelligence API

Customer API docs

Build with WaitTime Intelligence API.

Register a user, receive an API key, call protected endpoints with Bearer auth, and track quota usage. Swagger remains available at /docs for interactive exploration.

Download Postman collection OpenAPI JSON

Quickstart

Base URL http://127.0.0.1:8000
Demo API key dev_free_key
  1. Start the API with python -m uvicorn app.main:app --reload --port 8000.
  2. Call POST /v1/register to create a real customer key.
  3. Use Authorization: Bearer YOUR_API_KEY on protected endpoints.
  4. Call GET /v1/usage to inspect quota and per-endpoint usage.

Plans

Launch with a simple subscription ladder, then tune limits after real usage data arrives.

Plan Monthly price Included quota Feature access Best fit Upgrade
Free $0 100 requests per day Single predictions, places, usage, reports Testing and prototypes Register
Starter $19 10,000 requests per month Forecasts and nearby alternatives Small apps and pilots Subscribe
Pro $79 100,000 requests per month Batch predictions Production apps Subscribe
Business Custom Custom limits Custom feature and data terms Partners and high-volume teams Contact

Need help choosing a plan? Email support@termigpt.tech.

Billing

Register with the same email you use at checkout. During the first launch, paid access can be activated manually after payment or automatically through Stripe Checkout Session webhooks.

1Create an API account with POST /v1/register.
2Create checkout with POST /v1/billing/checkout.
3Use GET /v1/usage to confirm your active plan and quota.
Checkout 
curl -X POST http://127.0.0.1:8000/v1/billing/checkout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"plan\":\"starter\"}"

Authentication

Protected endpoints accept a Bearer token in the Authorization header.

Bearer auth 
Authorization: Bearer YOUR_API_KEY

Account and keys

POST

/v1/register

Create a user and receive an API key once.

Request 
curl -X POST http://127.0.0.1:8000/v1/register \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"customer@example.com\",\"name\":\"Example Customer\",\"company\":\"Example AB\"}"
GET

/v1/usage

Inspect current quota, remaining calls, period dates, and endpoint breakdown.

Request 
curl http://127.0.0.1:8000/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"
POST

/v1/api-key/recovery/request

Issue a forgotten-key recovery token. Local and test environments return the token in JSON.

Request 
curl -X POST http://127.0.0.1:8000/v1/api-key/recovery/request \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"customer@example.com\"}"
POST

/v1/api-key/recovery/confirm

Confirm recovery and receive a new API key. The previous key stops working.

Request 
curl -X POST http://127.0.0.1:8000/v1/api-key/recovery/confirm \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"customer@example.com\",\"recovery_token\":\"YOUR_RECOVERY_TOKEN\"}"
POST

/v1/api-key/regenerate

Rotate the current API key while keeping the same account and usage history.

Request 
curl -X POST http://127.0.0.1:8000/v1/api-key/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY"
POST

/v1/api-key/revoke

Disable the current API key immediately.

Request 
curl -X POST http://127.0.0.1:8000/v1/api-key/revoke \
  -H "Authorization: Bearer YOUR_API_KEY"

Predictions

You do not need a seeded catalog place ID to start. Send category, latitude, longitude, and place_name for your own location. Named customer locations return custom-location predictions. If no place_name is supplied and a nearby known place exists, the API can use that richer catalog record.

GET

/v1/wait-time

Predict wait time by place ID or by customer-provided category coordinates.

Request 
curl "http://127.0.0.1:8000/v1/wait-time?category=restaurant&latitude=59.3293&longitude=18.0686&place_name=Demo%20Restaurant&timezone=Europe%2FStockholm" \
  -H "Authorization: Bearer YOUR_API_KEY"
POST

/v1/wait-time/batch

Request up to 25 predictions in one call.

Request 
curl -X POST http://127.0.0.1:8000/v1/wait-time/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"requests\":[{\"place_id\":\"se-gbg-max-kungsportsavenyn\"},{\"category\":\"restaurant\",\"latitude\":59.3293,\"longitude\":18.0686,\"place_name\":\"Demo Restaurant\",\"timezone\":\"Europe/Stockholm\"}]}"
GET

/v1/forecast

Generate a slot-based forecast for the next hours.

Request 
curl "http://127.0.0.1:8000/v1/forecast?category=restaurant&latitude=59.3293&longitude=18.0686&hours=6&interval_minutes=60&timezone=Europe%2FStockholm" \
  -H "Authorization: Bearer YOUR_API_KEY"
GET

/v1/alternatives

Find nearby places in the same category with shorter waits.

Request 
curl "http://127.0.0.1:8000/v1/alternatives?latitude=57.7009&longitude=11.9746&category=supermarket&radius_km=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Catalog

Catalog endpoints are for demo places and known records. Predictions can also work for uncataloged customer locations by sending category and coordinates.

Method Path Purpose
GET /v1/places List seeded places, optionally filtered by category.
GET /v1/places/{place_id} Fetch one place record.
GET /v1/categories List categories with counts and typical waits.

Operations

Method Path Purpose
GET /health Public service health check.
POST /v1/report Submit a crowd-sourced wait observation.
GET /v1/insights/summary View seeded product analytics summary.

Errors

400Invalid or expired recovery token.
401Missing, malformed, invalid, or revoked API key.
404Unknown place or no nearby match.
409Email already registered.
422Invalid query or JSON body.
429Plan limit, registration limit, or recovery limit exceeded.