102 lines
2.0 KiB
Markdown
102 lines
2.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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):
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
uv run pytest
|
|
```
|
|
|
|
## OpenAPI
|
|
|
|
Generate the OpenAPI schema:
|
|
|
|
```bash
|
|
uv run python scripts/generate_openapi.py
|
|
```
|