Skip to content

USAGE.md

Latest commit

 

History

History
209 lines (144 loc) · 5.25 KB

USAGE.md

File metadata and controls

209 lines (144 loc) · 5.25 KB

Pinball Map Query - Detailed Usage Guide

This guide covers everything you need to know about using the pinball-map-query skill.

Quick Start

  1. Ensure you have Python 3 and the requests library installed:

    pip3 install requests

  2. Query a location:

    python3 pinball_query.py "Your Location Name"

Basic Usage

Searching for a Specific Venue

python3 pinball_query.py "Seattle Pinball Museum"

This finds the exact location and displays all pinball machines there.

Searching with Partial Names

The search is case-insensitive and supports partial matching:

# Search for any location containing "Admiral"
python3 pinball_query.py "Admiral"

# Search for any location containing "Pub"
python3 pinball_query.py "Pub"

# Search for any location containing "Tavern"
python3 pinball_query.py "Tavern"

Multi-word Location Names

Simply provide the full name in quotes:

python3 pinball_query.py "Ice Box Arcade"
python3 pinball_query.py "The Bullpen Tavern"

Understanding the Output

Successful Search Result

Searching for 'Seattle Pinball Museum' in Washington...
Fetching locations from Seattle and Spokane regions...
Found: Seattle Pinball Museum
Fetching machines...

Pinball tables at Seattle Pinball Museum:
==================================================
1. Medieval Madness
   Year: 1997 | Manufacturer: Williams
2. The Addams Family
   Year: 1992 | Manufacturer: Midway
3. Twilight Zone
   Year: 1993 | Manufacturer: Williams
==================================================
Total: 3 tables

Location Not Found

Location 'NonExistent Arcade' not found in Washington

Tip: Try searching with partial names. Available locations include:
  - Admiral Pub & Grill
  - Bake'n & Brain Tavern
  - Brass Tap Sports Bar
  - Great American Gaming
  - Ice Box Arcade

The tool provides a list of suggestions to help you refine your search.

Advanced Tips

Finding All Locations with a Specific Type

While the tool focuses on specific locations, you can explore by searching for common venue types:

# Search for all pubs with pinball
python3 pinball_query.py "Pub"

# Search for all taverns
python3 pinball_query.py "Tavern"

# Search for arcades
python3 pinball_query.py "Arcade"

Discovering New Machines

Run the script multiple times for different venues to discover the full variety of pinball machines available in Washington.

Troubleshooting

"Error fetching locations"

Issue: Network connection error when fetching from Pinball Map API

Solution:

"Location not found"

Issue: The venue you're looking for doesn't appear in results

Possible causes:

  • The location may not be in the Pinball Map database
  • The name might be slightly different than expected (try partial searches)
  • The venue may not have any pinball machines (so it's not included)

Solution:

  • Use shorter search terms for partial matching
  • Check the suggested locations provided by the tool
  • Visit pinballmap.com directly to check the database

ImportError: No module named 'requests'

Issue: Python can't find the requests library

Solution:

pip3 install requests

Or if you have multiple Python versions:

pip install requests

API Information

This skill uses the public Pinball Map API:

Supported Regions

  • Seattle Region - Western Washington locations
  • Spokane Region - Eastern Washington locations

API Endpoints Used

  • GET /region/{region}/locations.json - Fetch all locations in a region
  • GET /region/{region}/location_machine_xrefs.json - Fetch machine associations

Performance Notes

  • First run may take a few seconds as it fetches all Washington locations
  • Subsequent searches use the same data fetch
  • Network speed affects response time

Data Accuracy

  • Data is maintained by the Pinball Map community
  • Machines and locations may not be 100% current
  • Last visit/update information may not be reflected immediately
  • Consider verifying availability before planning a visit

Integration with Claude Code

This skill is designed to work within Claude Code environments:

  1. Place in your .claude/skills/pinball-map-query/ directory
  2. Use when researching or discovering pinball machines
  3. Helpful for planning venue visits based on machine availability

Examples for Different Scenarios

Planning a Pinball Gaming Session

# Check what's available at your preferred location
python3 pinball_query.py "Ice Box Arcade"

# Explore alternatives
python3 pinball_query.py "Admiral"
python3 pinball_query.py "Bullpen"

Researching a Specific Manufacturer's Presence

# Check multiple venues to see where Williams machines are located
python3 pinball_query.py "Location1"
python3 pinball_query.py "Location2"

Finding Vintage vs Modern Machines

Look at the year information in results - machines from 1980s-1990s are considered classics, while 2010+ are modern releases.