Local Search with Google Maps

Access Google Maps Places API through x402-protected endpoints.

Setup

See rules/getting-started.md for installation and wallet setup.

Quick Reference

See rules/partial-vs-full.md for tier selection guidance.

Text Search

Search for places by text query:

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/text-search/partial -m POST -b '{"textQuery": "coffee shops in downtown Seattle"}'

Parameters:

• textQuery - Search query (required)
• locationBias - Prefer results near a location
• minRating - Minimum rating filter (1-5)
• openNow - Only open places
• maxResultCount - Limit results (default: 20)

Full tier adds: reviews, atmosphere data, photos, price level.

Nearby Search

Search for places near a location:

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/nearby-search/partial -m POST -b '{
  "locationRestriction": {
    "circle": {
      "center": {"latitude": 47.6062, "longitude": -122.3321},
      "radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"]
}'

Parameters:

• locationRestriction - Circle with center (lat/lng) and radius in meters
• includedTypes - Place types to include
• excludedTypes - Place types to exclude
• minRating - Minimum rating
• openNow - Only open places

Place Details

Get detailed info for a specific place:

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/place-details/partial -m POST -b '{"placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4"}'

Input:

• placeId - Google Place ID (from search results)

Partial returns: Name, address, phone, website, hours, rating, types.

Full returns: + reviews, atmosphere (wheelchair access, pets allowed), photos, price level.

Common Place Types

Use these with includedTypes / excludedTypes:

Food & Drink: restaurant, cafe, bar, bakery, coffee_shop

Lodging: hotel, motel, lodging, guest_house

Shopping: shopping_mall, store, supermarket, clothing_store

Services: bank, atm, gas_station, car_repair, car_wash

Health: hospital, pharmacy, doctor, dentist

Entertainment: movie_theater, museum, park, gym

Workflows

Find Businesses in Area

• (Optional) Check balance: npx agentcash@latest wallet info
• Text search (partial) to find options
• Review results and select top picks
• Get full details for selected places

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/text-search/partial -m POST -b '{"textQuery": "Italian restaurants downtown Portland"}'

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/place-details/full -m POST -b '{"placeId": "ChIJ..."}'

Nearby Search with Filters

• Get coordinates for the area
• Search with location restriction and filters
• Present sorted results

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/nearby-search/partial -m POST -b '{
  "locationRestriction": {
    "circle": {
      "center": {"latitude": 40.7128, "longitude": -74.0060},
      "radius": 500
    }
  },
  "includedTypes": ["restaurant"],
  "minRating": 4.0,
  "openNow": true
}'

Compare Places with Reviews

• Search to get place IDs
• Fetch full details for each candidate
• Compare ratings, reviews, and amenities

npx agentcash@latest fetch https://stableenrich.dev/api/google-maps/place-details/full -m POST -b '{"placeId": "place_id_here"}'

Cost Optimization

Use Partial Tier When:

• Just need name, address, basic info
• Browsing/discovering options
• Initial search before drilling down

Use Full Tier When:

• Need reviews/ratings details
• Need atmosphere info (accessibility, etc.)
• Final decision-making

Efficient Patterns

1. Search partial, detail full:

   • Text search (partial) to find places
   • Place details (full) for the one you care about

2. Batch searches:

   • Combine filters to reduce calls
   • Use maxResultCount to limit results

3. Cache place IDs:

   • Place IDs are stable
   • Re-fetch details only when needed

Response Data

Partial Tier Fields

• name - Place name
• formattedAddress - Full address
• location - Lat/lng coordinates
• rating - Average rating (1-5)
• userRatingCount - Number of ratings
• types - Place type categories
• businessStatus - OPERATIONAL, CLOSED, etc.
• regularOpeningHours - Hours of operation
• nationalPhoneNumber - Phone number
• websiteUri - Website URL

Full Tier Additional Fields

• reviews - User reviews with text and ratings
• priceLevel - $ to $$$$
• accessibilityOptions - Wheelchair accessible, etc.
• parkingOptions - Parking availability
• paymentOptions - Accepted payment methods
• photos - Photo references