Documentation

Get started with Polyhistor in under 5 minutes. Build location-aware apps that understand context, not just coordinates.

Base URL: https://api.thepolyhistor.com  |  Current version: v1

Getting Started

Polyhistor is a contextual geospatial intelligence API. Unlike traditional place APIs that return raw coordinates and ratings, Polyhistor understands what a place feels like, when it's best to visit, and who it's for.

1

Join the waitlist

Pricing and self-serve API keys launch next week. Join the waitlist to get early access. For now, you can explore the live demo without an API key.

2

Make your first request

Once you have an API key, every request includes it in the X-API-Key header:

3

Integrate into your app

Use the Unified Search endpoint for most use cases. It combines semantic, temporal, and social signals into one ranked result set.

curl "https://api.thepolyhistor.com/api/v1/unified/search?query=cozy+coffee+shop&city=chicago&limit=5" \
  -H "X-API-Key: your_api_key_here"

Authentication

All API requests (except the public demo endpoint) require an API key. Include your key in the X-API-Key header.

Example
X-API-Key: dgx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Getting an API Key

  1. Sign up at the Developer Dashboard
  2. Create a new project
  3. Copy your API key from the project settings page
  4. Include the key in every request header

Security tip: Never expose your API key in client-side JavaScript. Proxy requests through your backend, or use the demo endpoint for client-side prototypes.

Rate Limits

Rate limits are enforced per API key. Limits vary by plan tier:

PlanRequests/minRequests/month
Free305,000
Pro300100,000
EnterpriseUnlimitedUnlimited

When you exceed a limit, the API returns 429 Too Many Requests. Retry after the time specified in the Retry-After header.

Suggestions

Category-based query suggestions and random query generation for discovery. No API key required.

GET/api/v1/suggestions

Returns categorized query suggestions with icons, descriptions, and example queries per city.

Example
curl "https://api.thepolyhistor.com/api/v1/suggestions"
Example
{
  "categories": [
    {
      "id": "work",
      "label": "Work",
      "icon": "💻",
      "description": "Quiet spaces to focus",
      "queries": [
        { "query": "quiet workspace with wifi", "city": "san_francisco", "cityLabel": "San Francisco" }
      ]
    }
  ],
  "meta": { "total_categories": 6, "total_queries": 24 }
}
GET/api/v1/suggestions/random

Returns a single random query suggestion with city pre-selected.

Example
curl "https://api.thepolyhistor.com/api/v1/suggestions/random"
Example
{
  "query": "romantic rooftop bar",
  "city": "san_francisco",
  "cityLabel": "San Francisco"
}
GET/api/v1/places/:id

Get details for a specific place by ID.

Parameters

ParameterTypeRequiredDescription
idstringRequiredPlace UUID
GET/api/v1/places/:id/enriched

Get place details with external enrichment data (photos, reviews, hours) if available.

GET/api/v1/temporal/state

Get the current temporal state of places in an area. Understands how a place changes character throughout the day.

Parameters

ParameterTypeRequiredDescription
placeIdstringOptionalSpecific place ID
latnumberOptionalLatitude (for area query)
lonnumberOptionalLongitude (for area query)
timestringOptionalTime in HH:MM format. Default: current time
GET/api/v1/tribe/heatmap

Get social density heatmap for a tribe segment. Uses Uber H3 hexagonal grid (resolution 9, ~0.1 km²).

Parameters

ParameterTypeRequiredDescription
tribe_idstringRequiredFOUNDER, STUDENT, CREATIVE, FOODIE, FITNESS, NIGHTLIFE, WELLNESS
citystringOptionalCity name
boundsstringOptionalBounding box: minLat,minLon,maxLat,maxLon
limitintegerOptionalMax heatmap cells. Default: 500
Example
curl "https://api.thepolyhistor.com/api/v1/tribe/heatmap?tribe_id=FOUNDER&city=chicago&limit=100" \
  -H "X-API-Key: your_api_key_here"
GET/api/v1/tribe/profiles

List all tribe definitions with metadata and category mappings.

GET/api/v1/trip/plan

Multi-stop itinerary planning with nearest-neighbor routing.

Parameters

ParameterTypeRequiredDescription
querystringRequiredTrip theme: "food tour", "coffee crawl", "bar hop"
citystringRequiredCity name
stopsintegerOptionalNumber of stops. Default: 5
startstringOptionalStart time HH:MM
Example
curl "https://api.thepolyhistor.com/api/v1/trip/plan?query=food+tour&city=nyc&stops=5&start=10:00" \
  -H "X-API-Key: your_api_key_here"

Waitlist

Join the waitlist for early access. No API key required.

POST/api/v1/waitlist

Subscribe to the waitlist. Returns success confirmation or error if already subscribed.

Parameters

ParameterTypeRequiredDescription
namestringRequiredFull name
emailstringRequiredEmail address
sourcestringOptionalSignup source for analytics (e.g., "waitlist_page")
curl -X POST "https://api.thepolyhistor.com/api/v1/waitlist" \  -H "Content-Type: application/json" \  -d '{"name":"Ada Lovelace","email":"ada@example.com","source":"docs_page"}'
Example
{
  "success": true,
  "waitlist_id": "wl_abc123"
}
GET/health

Deep health check — verifies database and Redis connectivity.

Example
{
  "status": "healthy",
  "services": {
    "database": "up",
    "redis": "up"
  }
}
GET/health/ping

Instant ping — responds immediately without checking dependencies. Use for load balancer health checks.

SDKs & Examples

We currently provide REST API access. Official SDKs are on the roadmap. In the meantime, here are copy-paste ready snippets for common patterns.

Unified Search

curl -G "https://api.thepolyhistor.com/api/v1/unified/search" \
  -H "X-API-Key: your_api_key_here" \
  --data-urlencode "query=romantic rooftop bar" \
  --data-urlencode "city=nyc" \
  --data-urlencode "limit=5"

Trip Planner

curl -G "https://api.thepolyhistor.com/api/v1/trip/plan" \
  -H "X-API-Key: your_api_key_here" \
  --data-urlencode "query=coffee crawl" \
  --data-urlencode "city=sf" \
  --data-urlencode "stops=4" \
  --data-urlencode "start=09:00"

Error Reference

Polyhistor uses standard HTTP response codes.

CodeMeaningHow to fix
200OKSuccess — parse the response body
400Bad RequestCheck parameter types and required fields
401UnauthorizedInclude a valid X-API-Key header
429Too Many RequestsWait for Retry-After seconds, then retry
500Server ErrorRetry with exponential backoff. Contact support if persistent.

Error Response Format

Example
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

Still have questions?

Join the Waitlist