Pinball Map Getting Started: API Access and First Request (2026)

Getting started overview

The Pinball Map API facilitates programmatic access to a comprehensive database of pinball machine locations, machine inventories, and event data. This guide outlines the steps required to initiate interaction with the API, covering account creation, obtaining necessary credentials, and executing a foundational API call. The API primarily uses a RESTful architectural style, returning data in JSON format.

For non-commercial applications, the Pinball Map API is available without charge, though commercial use requires specific licensing, as detailed in the Pinball Map API documentation. The API's design is straightforward, providing distinct endpoints for querying locations, specific machines, and scheduled events.

The following table summarizes the initial steps:

Create an account and get keys

For many public data retrieval endpoints, the Pinball Map API does not strictly require an API key or account registration. This allows for immediate experimentation and data access for common queries, such as listing locations or machines. However, creating an account on the Pinball Map website and potentially obtaining an API key becomes relevant for specific scenarios:

• Data Contribution: If you intend to add new locations, machines, or update existing data, a user account is necessary for authentication.
• Authenticated Endpoints: Certain API functionalities or higher rate limits may be tied to authenticated requests, requiring an API key. Review the Pinball Map API reference for details on which endpoints necessitate authentication.
• Commercial Use: For commercial applications, direct contact with Pinball Map is required for licensing, which may involve specific API access arrangements.

To create an account:

1. Navigate to the Pinball Map homepage.
2. Look for a "Sign Up" or "Register" link, typically located in the header or footer.
3. Follow the on-screen prompts to provide a username, email address, and password.
4. Verify your email address if prompted.

If an API key is required for your specific use case, instructions for generating and managing it will be provided within your account settings on the Pinball Map website or detailed within the Pinball Map API documentation. Typically, API keys are alphanumeric strings passed as a query parameter or an HTTP header, though the Pinball Map API primarily uses query parameters for keys when required.

Your first request

To make your first request, you can query a public endpoint that does not require authentication. A common starting point is to retrieve a list of regions or locations. We will use the /api/v1/regions.json endpoint to get a list of all available regions.

Endpoint: https://pinballmap.com/api/v1/regions.json

This endpoint returns a JSON array of regions, each containing details such as its name and slug.

Example using curl (command line):

curl "https://pinballmap.com/api/v1/regions.json"

Example using a web browser:

Simply paste https://pinballmap.com/api/v1/regions.json into your browser's address bar and press Enter. The browser will display the JSON response directly.

Expected JSON response structure (abbreviated):

{
  "regions": [
    {
      "id": 1,
      "name": "Portland",
      "full_name": "Portland, OR",
      "slug": "portland",
      "lat": 45.52345,
      "lon": -122.67621,
      "zoom": 12,
      "current_event_id": null,
      "events_count": 0,
      "url": "https://pinballmap.com/portland",
      "region_url": "https://pinballmap.com/api/v1/regions/portland",
      "num_machines": 1234,
      "num_locations": 567
    },
    {
      "id": 2,
      "name": "Seattle",
      "full_name": "Seattle, WA",
      "slug": "seattle",
      "lat": 47.60621,
      "lon": -122.33207,
      "zoom": 12,
      "current_event_id": null,
      "events_count": 0,
      "url": "https://pinballmap.com/seattle",
      "region_url": "https://pinballmap.com/api/v1/regions/seattle",
      "num_machines": 890,
      "num_locations": 345
    }
    // ... more regions
  ]
}

Once you have successfully received this response, you have confirmed basic connectivity and understanding of the API's response format. You can then proceed to more specific queries, such as listing locations within a particular region, by using the slug value from the region response.

For instance, to get locations in Portland, you would use an endpoint like https://pinballmap.com/api/v1/region/portland/locations.json.

Common next steps

After successfully making your initial API call, several common next steps can enhance your interaction with the Pinball Map API:

1. Explore Specific Endpoints: Review the Pinball Map API documentation to identify endpoints relevant to your project. Key endpoints include:

   • /api/v1/region/:region_slug/locations.json: Retrieve all locations within a specific region.
   • /api/v1/location/:location_id.json: Get details for a specific location, including its machines.
   • /api/v1/region/:region_slug/machines.json: List all machines in a particular region.
   • /api/v1/location/:location_id/machine/:machine_id.json: Access details for a specific machine at a specific location.
   • /api/v1/regions/:region_slug/events.json: Fetch upcoming events in a region.

2. Implement Query Parameters: Many endpoints support query parameters to filter, sort, or paginate results. For example, you might filter locations by machine type or sort events by date. Consult the API reference for supported parameters on each endpoint.

3. Handle Rate Limits: While specific rate limits for unauthenticated requests are not prominently published for the free tier, it is good practice to anticipate and handle them. Implement exponential backoff for retries to avoid overwhelming the API, as recommended by Google Cloud's API best practices for handling errors. For higher volume needs, consider authenticated access or contacting Pinball Map for commercial licensing.

4. Integrate with a Programming Language: To build a functional application, integrate the API calls into your chosen programming language. Libraries like requests in Python, fetch in JavaScript, or HttpClient in C# can simplify HTTP requests and JSON parsing.

5. Error Handling: Implement robust error handling in your application. The API will return standard HTTP status codes (e.g., 404 Not Found, 400 Bad Request, 500 Internal Server Error) along with JSON error messages. Your application should gracefully manage these responses.

6. Contribute Data: If your use case involves adding new pinball locations or updating machine status, explore the authenticated endpoints for data submission. This typically requires an API key associated with your user account.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps for the Pinball Map API:

• Check URL Accuracy: Verify that the endpoint URL is typed correctly, including "https://" and the exact path (e.g., /api/v1/regions.json). A common error is a typo in the slug or version number.

• Internet Connectivity: Ensure your device has an active internet connection. A simple test is to visit a well-known website like google.com in your browser.

• HTTP Client Issues: If using curl or another HTTP client, ensure it's installed correctly and you're using the correct syntax. For browser-based testing, check your browser's developer console (F12) for network errors.

• JSON Parsing Errors: If the response is not displaying as expected, your tool might be having trouble parsing the JSON. Most modern browsers automatically format JSON, but command-line tools might require piping the output to a JSON formatter (e.g., curl ... | jq . if jq is installed).

• API Key (if applicable): If you are attempting to access an endpoint that requires an API key, ensure it is included correctly as a query parameter or header, as specified in the Pinball Map API documentation. Incorrect or missing keys will typically result in a 401 Unauthorized or 403 Forbidden HTTP status code.

• Rate Limiting: If you make too many requests in a short period, you might encounter rate limiting, resulting in a 429 Too Many Requests status. Wait for a short period before retrying, or reduce your request frequency.

• Server-Side Issues: Occasionally, the API server itself might experience issues. If you receive a 5xx series HTTP status code (e.g., 500 Internal Server Error, 503 Service Unavailable), this indicates a problem on the server side. These are usually temporary; try again later.

• Consult Documentation: Re-read the relevant sections of the Pinball Map API reference for the specific endpoint you are trying to access. The documentation often provides error codes and troubleshooting tips.