Documentation

Overview

Camino AI gives your applications real-world location intelligence through a simple, developer-friendly API. Ask questions in natural language and get structured, accurate location data instantly.

Natural Language

Query places the way humans think: "quiet cafes with wifi near downtown"

AI-Powered Ranking

Results ranked by actual relevance, not just proximity

Plug & Play

Works with any language or framework. Simple REST API + MCP support

Real-Time Data

OpenStreetMap data updated continuously worldwide

What Can You Build?

AI Travel Assistants — Help users find hotels, restaurants, and attractions
Real Estate Tools — Analyze neighborhoods, nearby amenities, commute times
Logistics Applications — Route optimization, delivery planning, fleet management
Chatbots & Agents — Ground LLM responses in real location data
Research Tools — Analyze geographic patterns, find patterns in POI data

Quick Start

Get up and running in under 5 minutes.

Create an Account
Sign up at getcamino.ai/login with your Google account. You'll get 100 free API calls per month.
Get Your API Key
Go to your Dashboard and create an API key. Copy it somewhere safe.
Make Your First Query
Try this curl command (replace YOUR_KEY with your actual key):

curl "https://api.getcamino.ai/query" \ -H "X-API-Key: YOUR_KEY" \ --data-urlencode query="coffee shops in Times Square" \ --data-urlencode lat="40.758" \ --data-urlencode lon="-73.985"
Parse the Response
You'll receive structured JSON with places, coordinates, distances, and an AI-generated summary.

Tip

Don't have coordinates? The API can infer location from well-known place names like "Times Square" or "Eiffel Tower".

Authentication

All API requests require authentication via an API key.

Using Your API Key

Include your API key in the X-API-Key header:

curl "https://api.getcamino.ai/query?query=..." \
  -H "X-API-Key: cam_your_api_key_here"
                

Or as a query parameter (useful for MCP):

curl "https://api.getcamino.ai/query?query=...&caminoApiKey=cam_your_key"

Rate Limits

Free tier: 100 calls/month, 30 requests/minute
Paid: Unlimited calls, 60 requests/minute

Alternative: Pay-per-request via x402

Paid endpoints (/query, /search, /route, /relationship, /context, /journey) also accept x402 payments — no signup or API key required. Any x402-capable client can call the API and settle $0.001 per request in USDC on Base directly from a wallet.

When x402 is enabled, requests without an X-API-Key receive an HTTP 402 Payment Required response with the payment requirements payload at the top level (no detail wrapper). Re-send the request with a signed X-Payment header to settle and receive the response.

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "1000",
    "asset": "USDC",
    "payTo": "0x..."
  }]
}
                

Useful for agentic systems that should pay per-call without account setup. See the x402 spec for client libraries in Python, TypeScript, and Go.

Natural Language Query

The core endpoint for finding places using natural language.

GET /query

Search for places using natural language queries with optional AI ranking.

Parameter	Type	Description
query *	string	Natural language search query
lat	float	Latitude (recommended for best results)
lon	float	Longitude (recommended for best results)
radius	int	Search radius in meters (default: 1000)
limit	int	Max results to return (default: 20, max: 100)
rank	bool	Use AI ranking (default: true)
answer	bool	Include AI-generated summary (default: true)

Example Response

{
  "query": "coffee shops in Times Square",
  "results": [
    {
      "name": "Blue Bottle Coffee",
      "lat": 40.7580,
      "lon": -73.9855,
      "address": "1 Times Square, New York",
      "distance_m": 120,
      "relevance_score": 0.95
    }
  ],
  "answer": "I found 12 coffee shops near Times Square...",
  "count": 12
}
                

Search & Geocoding

Look up specific named places or geocode addresses using either a free-form query or structured address components. Use /search when you know what you're looking for ("Eiffel Tower", "123 Main St, Brooklyn"); use /query for natural-language discovery with AI ranking.

POST /search

Search for places by name or by address. Use query for free-form text, or structured params for specific fields. If you supply both, they're merged into a single query (the free-form name carries the most weight, followed by the structured tokens).

Parameter	Type	Description
query	string	Free-form search query (e.g. "Eiffel Tower"). Can be combined with structured params; they'll be merged.
amenity	string	Name and/or type of POI (e.g. "restaurant", "Starbucks")
street	string	Street with optional house number (e.g. "123 Main Street")
city	string	City name (e.g. "Paris", "New York")
county	string	County or district name
state	string	State or province (e.g. "California", "Ontario")
country	string	Country name (e.g. "France", "United States")
postalcode	string	Postal or ZIP code
limit	int	Max results to return (default: 10, max: 50)
include_photos	bool	Attach street-level imagery from OpenStreetCam (default: false)
photo_radius	int	Search radius for street photos in meters (default: 100, range: 10-500)
mode	string	"basic" (free, OSM only) or "advanced" (web enrichment + AWS fallback)

Example Response

[
  {
    "display_name": "Eiffel Tower, Champ de Mars, Paris, France",
    "lat": 48.8584,
    "lon": 2.2945,
    "type": "tourism",
    "importance": 0.91,
    "source": "nominatim"
  }
]
                

Route Planning

Calculate routes between points with distance, duration, and turn-by-turn directions.

GET /route

Get directions between two points.

Parameter	Type	Description
start_lat *	float	Starting latitude
start_lon *	float	Starting longitude
end_lat *	float	Destination latitude
end_lon *	float	Destination longitude
mode	string	Transport mode: car, bike, foot (default: car)

Spatial Relationships

Understand the relationship between two locations — distance, direction, travel time.

POST /relationship

Analyze the spatial relationship between two points.

{
  "start": { "lat": 40.7580, "lon": -73.9855 },
  "end": { "lat": 40.7484, "lon": -73.9857 },
  "include": ["distance", "direction", "travel_time", "description"]
}
                        

Place Context

Get contextual information about what's around a specific location.

POST /context

Understand the surroundings of a location.

{
  "location": { "lat": 40.7580, "lon": -73.9855 },
  "radius": "500m",
  "context": "evaluating for a new office location"
}
                        

Journey Planning

Plan multi-stop trips with time budgets and transport constraints.

POST /journey

Create optimized multi-stop itineraries.

{
  "waypoints": [
    { "lat": 40.758, "lon": -73.985, "purpose": "Start at Times Square" },
    { "lat": 40.748, "lon": -73.985, "purpose": "Visit Empire State Building" }
  ],
  "constraints": {
    "transport": "walking",
    "time_budget": "2 hours"
  }
}
                        

Deep Research Report

Submit a topic + an anchor coordinate; receive a research report where every recommended venue is cross-checked against OpenStreetMap. Out-of-radius and wrong-city matches are dropped into drift_warnings so they never appear as "verified."

Async by design

Reports take 60–90 seconds. POST returns a job_id immediately; poll the GET endpoint until status is complete or failed. The job_id (UUIDv4) is the bearer credential for the GET — no API key needed on the poll request.

Submit a research job

POST /report

Returns job_id + poll_url immediately.

{
  "topic": "best craft breweries with food in NoDa Charlotte",
  "location": {
    "center": { "lat": 35.247, "lon": -80.811 },
    "radius_m": 2000
  },
  "secure": false
}
                        

Response:

{
  "job_id": "rpt_e0db052c7ec646c0abe9216c7aeb5363",
  "status": "pending",
  "poll_url": "https://api.getcamino.ai/report/rpt_e0db052c7ec646c0abe9216c7aeb5363",
  "estimated_seconds": 20,
  "secret": null
}
                        

Request fields

topic (required, 3–400 chars) — natural-language research prompt
location (optional) — { center: {lat, lon}, radius_m: 50–5000 }. When supplied, the report includes verified addresses + walking distance from the anchor
secure (optional, default false) — when true, the response includes a secret string and every GET /report/{job_id} must present it via X-Report-Secret header. Use this when the job_id will travel through environments where URLs/logs could leak it. See the "Secured retrieval" section below.

Poll for results

GET /report/{job_id}

No X-API-Key header required — the unguessable job_id is the credential (plus the optional X-Report-Secret header when the job was submitted with secure: true). Status cycles pending → complete or failed; stop polling once status is terminal.

Successful response:

{
  "job_id": "rpt_e0db052c...",
  "status": "complete",
  "result": {
    "topic": "best craft breweries...",
    "summary": "## NoDa Breweries\\n\\n**NoDa Brewing Company** at 2921 N Tryon...",
    "verified_places": [
      {
        "name": "NoDa Brewing Company",
        "address": "2921 N Tryon St, NoDa, Charlotte...",
        "lat": 35.2516, "lon": -80.8087,
        "distance_m": 508,
        "category": "brewery",
        "verification": "verified",
        "source": "nominatim"
      }
    ],
    "drift_warnings": [
      "Protagonist Clubhouse (7784.8km from anchor — likely different place, dropped)"
    ],
    "citations": [
      { "title": "NoDa Brewing on Untappd", "url": "https://untappd.com/..." }
    ]
  }
}
                        

Response fields

summary — markdown prose with inline citation markers like [1]; verified addresses + walking distances woven into the recommendations.
verified_places[] — each recommended venue cross-checked against OpenStreetMap. verification: "verified" when the place is in OSM and within the radius; "unverified" when Tavily cited a place not in OSM (kept so new/small businesses aren't silently dropped).
drift_warnings[] — venues the pipeline deliberately filtered. Most common reasons: outside the requested radius, or 5x+ outside (almost certainly a same-name place in a different city).
citations[] — the web sources from the research pass; cited inline in summary.

Secured retrieval

By default the job_id alone is the credential for GET. The UUIDv4 carries ~122 bits of entropy and is unguessable, but if it leaks (URL sharing, browser history, log files), anyone who has it can read the report. For sensitive briefs, set secure: true on submit:

curl -X POST "https://api.getcamino.ai/report" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic": "...", "location": {...}, "secure": true}'

# Response includes a one-shot `secret` string:
# {"job_id": "rpt_...", "secret": "k9_xs8...", ...}

# Every subsequent GET must include the X-Report-Secret header:
curl "https://api.getcamino.ai/report/rpt_..." \
  -H "X-Report-Secret: k9_xs8..."
                

The plain secret is returned exactly once on submit — capture it. The server stores only a SHA-256 hash. A GET with no/wrong secret on a secured job returns 404 (same response shape as a non-existent job — no existence disclosure). Jobs submitted without secure: true continue to retrieve without a header.

Retention (48-hour TTL)

Every report doc carries an expires_at timestamp set to 48 hours after submit. Firestore's native TTL sweep auto-deletes expired docs (typically within ~24h of expiry; not instant). After that, GET /report/{job_id} returns 404 indistinguishably from "never existed." Plan your polling cadence accordingly — if you need the report beyond 48h, archive the GET response on your side.

See it in action

/research walks through three real report outputs with the verified addresses, drift catches, and synthesizer prose called out side by side.

MCP Server Integration

Camino provides a remote MCP (Model Context Protocol) server, allowing AI assistants like Claude to use location intelligence directly — no local installation required.

What is MCP?

Model Context Protocol is a standard that lets AI assistants use external tools. With Camino's MCP server, Claude can search for places, plan routes, and answer location questions natively.

Claude Desktop Configuration

Add this to your Claude Desktop config file:

{
  "mcpServers": {
    "camino-ai": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-remote@latest",
        "https://api.getcamino.ai/mcp/sse?caminoApiKey=YOUR_KEY"
      ]
    }
  }
}
                

Cursor IDE Configuration

Same configuration works for Cursor:

{
  "mcpServers": {
    "camino-ai": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-remote@latest",
        "https://api.getcamino.ai/mcp/sse?caminoApiKey=YOUR_KEY"
      ]
    }
  }
}
                

Available MCP Tools

camino_query — Search for places using natural language
camino_route — Get directions between points
camino_relationship — Analyze spatial relationships
camino_context — Get context about a location
camino_journey — Plan multi-stop trips

SDKs & Integrations

Camino works with any HTTP client. Here are some popular integrations:

📖

Python Example

import requests

response = requests.get(
    "https://api.getcamino.ai/query",
    headers={"X-API-Key": "YOUR_KEY"},
    params={
        "query": "best pizza near Central Park",
        "lat": 40.7829,
        "lon": -73.9654
    }
)
data = response.json()
print(data["answer"])
                

JavaScript Example

const response = await fetch(
  `https://api.getcamino.ai/query?query=coffee+shops&lat=40.758&lon=-73.985`,
  { headers: { 'X-API-Key': 'YOUR_KEY' } }
);
const data = await response.json();
console.log(data.answer);
                

Overview

Natural Language

AI-Powered Ranking

Plug & Play

Real-Time Data

What Can You Build?

Quick Start

Authentication

Using Your API Key

Rate Limits

Alternative: Pay-per-request via x402

Natural Language Query

Example Response

Search & Geocoding

Example Response

Route Planning

Spatial Relationships

Place Context

Journey Planning

Deep Research Report

Submit a research job

Request fields

Poll for results

Response fields

Secured retrieval

Retention (48-hour TTL)

MCP Server Integration

Claude Desktop Configuration

Cursor IDE Configuration

Available MCP Tools

SDKs & Integrations

OpenAPI Spec

LangChain

LlamaIndex

n8n

Python Example

JavaScript Example

Create your account

Documentation

Overview

Natural Language

AI-Powered Ranking

Plug & Play

Real-Time Data

What Can You Build?

Quick Start

Authentication

Using Your API Key

Rate Limits

Alternative: Pay-per-request via x402

Natural Language Query

Example Response

Search & Geocoding

Example Response

Route Planning

Spatial Relationships

Place Context

Journey Planning

Deep Research Report

Submit a research job

Request fields

Poll for results

Response fields

Secured retrieval

Retention (48-hour TTL)

MCP Server Integration

Claude Desktop Configuration

Cursor IDE Configuration

Available MCP Tools

SDKs & Integrations

OpenAPI Spec

LangChain

LlamaIndex

n8n

Python Example

JavaScript Example