Pinball Map

# Pinball Map API Pinball Map (pinballmap.com) is a crowdsourced directory of pinball machines at locations worldwide. This document is for AI coding assistants helping developers build apps against this API. Full interactive documentation: https://pinballmap.com/api/v1/docs ## Base URL and Format All API endpoints are under: `https://pinballmap.com/api/v1/` Append `.json` to any endpoint (e.g. `GET /api/v1/locations.json`). All responses are JSON. ## Authentication Read-only (GET) endpoints are public — no auth required. Write operations (POST, PUT, DELETE) require a user account. Pass credentials as query params on every write request: ``` user_email=user@example.com&user_token=abc123 ``` Obtain a token by calling `GET /api/v1/users/auth_details.json?login=user@example.com&password=secret`. The response includes `authentication_token`. Store it; do not re-fetch the token on every request. ## Critical: Request Volume Anti-Patterns **If your app is making hundreds of requests, it is almost certainly designed incorrectly.** The API provides bulk endpoints that return many records in a single response. There is no legitimate use case that requires looping over individual location, machine, or LMX records one at a time. Examples of broken patterns and their correct replacements: | Wrong (N+1) | Correct (one request) | |---|---| | Loop calling `GET /locations/:id` for each location | `GET /locations.json?region=portland` — returns all locations in a region | | Loop calling `GET /locations/:id` with machine filter | `GET /locations.json?by_machine_id=41` — returns all locations with that machine | | Loop calling `GET /location_machine_xrefs/:id` for each LMX | `GET /region/:region/location_machine_xrefs.json` — returns all LMXs for a region | | Loop calling `GET /machine_score_xrefs/:id` for each score | `GET /machine_score_xrefs/highest.json` — returns highest score per machine | A well-designed client typically makes fewer than 10 API calls fo