clawdbot/skills/local-places/SERVER_README.md

Local Places

This repo is a fusion of two pieces:

• A FastAPI server that exposes endpoints for searching and resolving places via the Google Maps Places API.
• A companion agent skill that explains how to use the API and can call it to find places efficiently.

Together, the skill and server let an agent turn natural-language place queries into structured results quickly.

Run locally

# copy skill definition into the relevant folder (where the agent looks for it)
# then run the server

uv venv
uv pip install -e ".[dev]"
uv run --env-file .env uvicorn local_places.main:app --host 0.0.0.0 --reload

Open the API docs at http://127.0.0.1:8000/docs.

Places API

Set the Google Places API key before running:

export GOOGLE_PLACES_API_KEY="your-key"

Endpoints:

• POST /places/search (free-text query + filters)
• GET /places/{place_id} (place details)
• POST /locations/resolve (resolve a user-provided location string)

Example search request:

{
  "query": "italian restaurant",
  "filters": {
    "types": ["restaurant"],
    "open_now": true,
    "min_rating": 4.0,
    "price_levels": [1, 2]
  },
  "limit": 10
}

Notes:

• filters.types supports a single type (mapped to Google includedType).

Example search request (curl):

curl -X POST http://127.0.0.1:8000/places/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "italian restaurant",
    "location_bias": {
      "lat": 40.8065,
      "lng": -73.9719,
      "radius_m": 3000
    },
    "filters": {
      "types": ["restaurant"],
      "open_now": true,
      "min_rating": 4.0,
      "price_levels": [1, 2, 3]
    },
    "limit": 10
  }'

Example resolve request (curl):

curl -X POST http://127.0.0.1:8000/locations/resolve \
  -H "Content-Type: application/json" \
  -d '{
    "location_text": "Riverside Park, New York",
    "limit": 5
  }'

Test

uv run pytest

OpenAPI

Generate the OpenAPI schema:

uv run python scripts/generate_openapi.py