local-search

What this skill does

# Local Search with Google Maps

Access Google Maps Places API through x402-protected endpoints.

## Setup

See [rules/getting-started.md](rules/getting-started.md) for installation and wallet setup.

## Quick Reference

| Task | Endpoint | Price | Data Included |
|------|----------|-------|---------------|
| Text search (basic) | `https://stableenrich.dev/api/google-maps/text-search/partial` | $0.02 | Name, address, rating |
| Text search (full) | `https://stableenrich.dev/api/google-maps/text-search/full` | $0.08 | + reviews, atmosphere |
| Nearby search (basic) | `https://stableenrich.dev/api/google-maps/nearby-search/partial` | $0.02 | Name, address, rating |
| Nearby search (full) | `https://stableenrich.dev/api/google-maps/nearby-search/full` | $0.08 | + reviews, atmosphere |
| Place details (basic) | `https://stableenrich.dev/api/google-maps/place-details/partial` | $0.02 | Core info |
| Place details (full) | `https://stableenrich.dev/api/google-maps/place-details/full` | $0.05 | All fields |

See [rules/partial-vs-full.md](rules/partial-vs-full.md) for tier selection guidance.

## Text Search

Search for places by text query:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/google-maps/text-search/partial",
  method="POST",
  body={
    "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:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/google-maps/nearby-search/partial",
  method="POST",
  body={
    "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:

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/google-maps/place-details/partial?placeId=ChIJN1t_tDeuEmsRUsoyG83frY4",
  method="GET"
)
```

**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: `agentcash.get_balance`
- [ ] Text search (partial) to find options
- [ ] Review results and select top picks
- [ ] Get full details for selected places

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/google-maps/text-search/partial",
  method="POST",
  body={"textQuery": "Italian restaurants downtown Portland"}
)
```

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/google-maps/place-details/full?placeId=ChIJ...",
  method="GET"
)
```

### Nearby Search with Filters

- [ ] Get coordinates for the area
- [ ] Search with location restriction and filters
- [ ] Present sorted results

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/google-maps/nearby-search/partial",
  method="POST",
  body={
    "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

```mcp
agentcash.fetch(
  url="https://stableenrich.dev/api/google-maps/place-details/full?placeId=place_id_here",
  method="GET"
)
```

## 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