Pinball Map APIpinballmap.com ↗
Search pinball machine locations worldwide by address or coordinates. Get location details, machine catalogs, IPDB/OPDB IDs, and condition notes via 3 endpoints.
What is the Pinball Map API?
The Pinball Map API exposes 3 endpoints covering publicly reported pinball machine locations worldwide. Use search_locations to find venues near a city, address, or lat/lon pair — with optional filtering by machine name or ID — then drill into a specific venue with get_location or retrieve its full machine catalog with get_location_machines, including IPDB and OPDB identifiers, manufacturer, and release year.
curl -X GET 'https://api.parse.bot/scraper/73f32a2e-b2a5-4952-8f38-ec42c8b66af5/search_locations?lat=45.5231&lon=-122.6765&address=Portland%2C+OR&machine_id=3099&machine_name=The+Addams+Family&max_distance=10' \ -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 pinballmap-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.
"""Walkthrough: PinballMap SDK — find pinball near you, drill into locations."""
from parse_apis.pinballmap_com_api import PinballMap, LocationNotFound
client = PinballMap()
# Search for pinball locations near a city, capped at 5 results.
for loc in client.location_summaries.search(address="Portland, OR", max_distance="5", limit=5):
print(loc.name, f"({loc.distance:.1f} mi)", loc.num_machines, "machines")
# Drill into the first result to see full details and machine lineup.
summary = client.location_summaries.search(address="Seattle, WA", limit=1).first()
if summary:
location = summary.details()
print(location.name, location.street, location.city, location.state)
print("Description:", location.description)
print("Last updated:", location.date_last_updated, "by", location.last_updated_by_username)
# List the machine catalog entries at this location.
for machine in location.machines.list(limit=5):
print(f" {machine.name} ({machine.manufacturer}, {machine.year})")
# Direct location lookup by known ID.
try:
spot = client.locations.get(location_id="874")
print(spot.name, "-", spot.num_machines, "machines")
for p in spot.placements[:2]:
print(f" Machine ID {p.machine_id}, added {p.created_at}")
except LocationNotFound as exc:
print(f"Location gone: {exc}")
print("exercised: location_summaries.search / details / locations.get / machines.list")
Search for pinball locations within a radius of a city/address or geographic coordinates. Returns locations sorted by distance, each with address, coordinates, machine count, machine names, and last-updated date. When no locations match, returns an empty list. The by_machine_name filter requires the canonical machine title (e.g. 'The Addams Family', 'The Munsters (Pro)') — partial matches are not supported.
| Param | Type | Description |
|---|---|---|
| lat | string | Latitude of search center (e.g. '45.5231'). Must be provided together with lon if address is omitted. |
| lon | string | Longitude of search center (e.g. '-122.6765'). Must be provided together with lat if address is omitted. |
| address | string | City, address, or place name to search near (e.g. 'Portland, OR', 'Seattle, WA'). Either address or both lat and lon must be provided. |
| machine_id | string | Filter results to locations that have this machine by numeric ID (from get_location_machines results). |
| machine_name | string | Filter results to locations that have this machine title. Must be the canonical machine name (e.g. 'The Addams Family', 'The Munsters (Pro)'). |
| max_distance | string | Maximum search radius in miles. |
{
"type": "object",
"fields": {
"total": "integer",
"locations": "array of location summaries with id, name, address fields, coordinates, distance, num_machines, machine_names, and date_last_updated"
},
"sample": {
"data": {
"total": 69,
"locations": [
{
"id": 10704,
"lat": "47.6010496",
"lon": "-122.3333214",
"zip": "98104",
"city": "Seattle",
"name": "The Meyer",
"phone": "+1 (555) 012-3456",
"state": "WA",
"street": "118 South Washington St",
"country": "US",
"website": "https://www.themeyerbar.com/",
"distance": 0.25,
"description": "Pirate-themed bar with pizza slices and bar games",
"num_machines": 3,
"machine_names": [
"Jurassic Park (LE) (Stern, 2019)",
"Twilight Zone (Bally, 1993)"
],
"date_last_updated": "2026-06-13"
}
]
},
"status": "success"
}
}About the Pinball Map API
What the API Covers
All three endpoints draw from the Pinball Map community database at pinballmap.com, which tracks publicly accessible locations — arcades, bars, laundromats, and similar venues — that have pinball machines available for play. Coverage is global but density reflects where the community has submitted reports.
Searching for Locations
search_locations accepts either an address string (city, street, or place name) or a lat/lon pair as the search center, with an optional max_distance radius in miles. Results are sorted by distance and each entry includes the location id, name, street, city, state, country, lat, lon, num_machines, a machine_names list, and a date_last_updated timestamp. You can pre-filter results to a specific machine using either machine_id (numeric) or machine_name (canonical title string such as 'The Addams Family').
Location Details and Machine Catalog
get_location takes a numeric location_id and returns the full venue record: street address fields, ZIP code, phone number, hours, a freeform description, last-updated metadata, and per-machine placement records that include condition comments and timestamps. get_location_machines returns a separate array of machine catalog entries — each with id, name, year, manufacturer, ipdb_id, and opdb_id — giving you the reference data needed to look up titles in the Internet Pinball Database or Open Pinball Database. The two endpoints complement each other: get_location gives operational status while get_location_machines gives catalog identity.
Identifiers and Cross-Referencing
Machine IDs returned by get_location_machines are the same integers accepted by the machine_id filter in search_locations, so you can build a two-step lookup: find a machine's ID from one location, then search for every other location carrying the same title.
The Pinball Map API is a managed, monitored endpoint for pinballmap.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when pinballmap.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 pinballmap.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?+
- Build a 'find pinball near me' feature using lat/lon search and the distance field in search_locations results.
- Filter venues by a specific title using machine_name to map every location carrying a classic machine like 'Medieval Madness'.
- Cross-reference IPDB and OPDB IDs from get_location_machines to enrich a pinball title database with known locations.
- Display venue contact info, hours, and description from get_location for a location-detail screen in a mobile app.
- Track machine condition notes and last-updated timestamps from get_location to surface recently updated venues.
- Aggregate num_machines counts across a metro area to rank cities by pinball density.
- Resolve a machine's canonical name and manufacturer year before presenting it to end users, using get_location_machines fields.
| 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.