Back to Details

local-places

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

📍 Local Places

📍 本地场所搜索

Find places, Go fast
Search for nearby places using a local Google Places API proxy. Two-step flow: resolve location first, then search.
快速查找场所
使用本地Google Places API代理搜索附近场所。分为两步流程：先解析位置，再进行搜索。

Setup

安装配置

bash
cd {baseDir}
echo "GOOGLE_PLACES_API_KEY=your-key" > .env
uv venv && uv pip install -e ".[dev]"
uv run --env-file .env uvicorn local_places.main:app --host 127.0.0.1 --port 8000
Requires 
GOOGLE_PLACES_API_KEY
in 
.env
or environment.
bash
cd {baseDir}
echo "GOOGLE_PLACES_API_KEY=your-key" > .env
uv venv && uv pip install -e ".[dev]"
uv run --env-file .env uvicorn local_places.main:app --host 127.0.0.1 --port 8000
需要在.env文件或环境变量中配置
GOOGLE_PLACES_API_KEY
。

Quick Start

快速开始

  1. Check server: 
    curl http://127.0.0.1:8000/ping
  2. Resolve location:
bash
curl -X POST http://127.0.0.1:8000/locations/resolve \
  -H "Content-Type: application/json" \
  -d '{"location_text": "Soho, London", "limit": 5}'
  1. Search places:
bash
curl -X POST http://127.0.0.1:8000/places/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "coffee shop",
    "location_bias": {"lat": 51.5137, "lng": -0.1366, "radius_m": 1000},
    "filters": {"open_now": true, "min_rating": 4.0},
    "limit": 10
  }'
  1. Get details:
bash
curl http://127.0.0.1:8000/places/{place_id}
  1. 检查服务器：
    curl http://127.0.0.1:8000/ping
  2. 解析位置：
bash
curl -X POST http://127.0.0.1:8000/locations/resolve \
  -H "Content-Type: application/json" \
  -d '{"location_text": "Soho, London", "limit": 5}'
  1. 搜索场所：
bash
curl -X POST http://127.0.0.1:8000/places/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "coffee shop",
    "location_bias": {"lat": 51.5137, "lng": -0.1366, "radius_m": 1000},
    "filters": {"open_now": true, "min_rating": 4.0},
    "limit": 10
  }'
  1. 获取详情：
bash
curl http://127.0.0.1:8000/places/{place_id}

Conversation Flow

对话流程

  1. If user says "near me" or gives vague location → resolve it first
  2. If multiple results → show numbered list, ask user to pick
  3. Ask for preferences: type, open now, rating, price level
  4. Search with 
    location_bias
    from chosen location
  5. Present results with name, rating, address, open status
  6. Offer to fetch details or refine search
  1. 如果用户说“在我附近”或给出模糊位置 → 先解析位置
  2. 如果有多个结果 → 显示编号列表，让用户选择
  3. 询问偏好：类型、是否营业、评分、价格等级
  4. 使用所选位置的
    location_bias
    进行搜索
  5. 展示结果，包含名称、评分、地址、营业状态
  6. 提供获取详情或优化搜索的选项

Filter Constraints

过滤条件限制

  • filters.types
    : exactly ONE type (e.g., "restaurant", "cafe", "gym")
  • filters.price_levels
    : integers 0-4 (0=free, 4=very expensive)
  • filters.min_rating
    : 0-5 in 0.5 increments
  • filters.open_now
    : boolean
  • limit
    : 1-20 for search, 1-10 for resolve
  • location_bias.radius_m
    : must be > 0
  • filters.types
    ：必须是一种类型（例如“restaurant”、“cafe”、“gym”）
  • filters.price_levels
    ：整数0-4（0=免费，4=非常昂贵）
  • filters.min_rating
    ：0-5，步长0.5
  • filters.open_now
    ：布尔值
  • limit
    ：搜索请求为1-20，解析请求为1-10
  • location_bias.radius_m
    ：必须大于0

Response Format

响应格式

json
{
  "results": [
    {
      "place_id": "ChIJ...",
      "name": "Coffee Shop",
      "address": "123 Main St",
      "location": { "lat": 51.5, "lng": -0.1 },
      "rating": 4.6,
      "price_level": 2,
      "types": ["cafe", "food"],
      "open_now": true
    }
  ],
  "next_page_token": "..."
}
Use 
next_page_token
as 
page_token
in next request for more results.
json
{
  "results": [
    {
      "place_id": "ChIJ...",
      "name": "Coffee Shop",
      "address": "123 Main St",
      "location": { "lat": 51.5, "lng": -0.1 },
      "rating": 4.6,
      "price_level": 2,
      "types": ["cafe", "food"],
      "open_now": true
    }
  ],
  "next_page_token": "..."
}
在下次请求中使用
next_page_token
作为
page_token
参数以获取更多结果。