Local Search

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?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 balance
• [ ] 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?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?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

Getting Started

Setup

1. Install the agentcash CLI:

   npm install -g agentcash

2. Check wallet:

   npx agentcash@latest balance

3. Fund wallet (if needed):

• Redeem invite: npx agentcash@latest redeem YOUR_CODE
• Or run npx agentcash@latest accounts to get Base or Solana deposit links and wallet addresses

Troubleshooting

Partial vs Full Tier Selection

Google Maps endpoints offer two pricing tiers. Choose based on what data you need.

Quick Decision

Partial Tier ($0.02)

Included:

• Place name and address
• Location coordinates
• Basic rating (number)
• User rating count
• Business status
• Opening hours
• Phone and website
• Place types

Best for:

• Initial search/discovery
• Building lists of options
• Basic info lookup
• When reviews don't matter

Full Tier ($0.05-0.08)

Additional fields:

• Full review text and author info
• Price level ($ to $$$$)
• Accessibility options
• Parking information
• Payment methods accepted
• Photo references
• Atmosphere details

Best for:

• Final decision-making
• When reviews are important
• Accessibility research
• Detailed comparisons

Cost Comparison

Recommended Pattern

1. Search with partial: Find candidates cheaply 2. Detail with full: Get reviews for top picks

Example:

# Step 1: Partial search ($0.02)
text-search/partial -> 20 results

# Step 2: Full details on top 3 ($0.15)
place-details/full -> reviews, atmosphere

Total: $0.17 instead of $1.60 for all full searches.

When to Use Full for Search

Use full-tier search when:

• You need reviews for ALL results
• Comparing many places at once
• Atmosphere matters for every option

Otherwise, search partial and get full details selectively.