API Documentation

Base URL: https://poiagent.com

All endpoints return flat JSON with a meta field. No authentication required. Rate limited by IP.

POST/api/v1/search

Search for places by text query, optionally filtered by location.

Request Body

{ "query": "coffee shops in Tokyo", "lat": 35.6762, "lng": 139.6503, "radius": 10 }

Response

{
  "results": [
    {
      "id": "poi_0001",
      "name": "Fuglen Tokyo",
      "address": "...",
      "lat": 35.6792,
      "lng": 139.6403,
      "category": "cafe",
      "subcategory": "specialty coffee",
      "rating": 4.6,
      "review_count": 823,
      "tags": ["coffee", "norwegian", "vintage"]
    }
  ],
  "meta": { "total": 1, "took_ms": 3, "api_version": "v1" }
}
POST/api/v1/lookup

Get a deep research card for a single place by ID.

Request Body

{ "place_id": "poi_0001" }

Response

{
  "place": { "id": "poi_0001", "name": "...", "hours": {...}, "description": "...", ... },
  "nearby": [ ... ],
  "meta": { "total": 1, "took_ms": 2, "api_version": "v1" }
}
GET/api/v1/categories

List all available place categories.

Response

{
  "categories": ["restaurant", "cafe", "hotel", "museum", "park", ...],
  "meta": { "total": 15, "took_ms": 0, "api_version": "v1" }
}

Error Handling

Errors return a JSON object with an error field and appropriate HTTP status code.

{
  "error": "Missing required field: query",
  "meta": { "api_version": "v1" }
}