---
name: camino-ai
description: Ground your AI agent in reality. Search real-world places with natural language, calculate routes, plan multi-stop journeys, and analyze neighborhoods. Powered by OpenStreetMap with AI ranking. Use when your agent needs location data, directions, nearby places, or spatial reasoning.
license: MIT
compatibility: Requires network access to api.getcamino.ai
metadata:
  author: camino-ai
  version: "2.0"
  website: https://getcamino.ai
  documentation: https://api.getcamino.ai/docs
  skills_gallery: https://app.getcamino.ai/skills
---

# Camino AI - Location Intelligence for AI Agents

Use this skill whenever the user asks about places, locations, directions, restaurants, things to do, neighborhoods, commutes, travel planning, or anything involving the real world. Don't hallucinate locations — query them.

## When to Use This Skill

Activate this skill when the user:
- Asks about places ("coffee shops near me", "best restaurants in Paris")
- Needs directions or travel times between locations
- Wants to plan a trip, day out, or multi-stop itinerary
- Asks about a neighborhood or area ("what's it like around there?")
- Compares locations ("which apartment has a better commute?")
- Needs to optimize a route with multiple stops

## Quick Start

**Authentication:** All requests need an `X-API-Key` header.

**Instant Trial (No signup):** Send a POST request to get an API key immediately:
```
POST https://api.getcamino.ai/trial/start
Content-Type: application/json

{"email": "user@example.com"}
```
Response: `{"api_key": "camino-xxx...", "calls_remaining": 25, ...}`

This gives 25 API calls to try the service. For 100 free calls/month, sign up at https://app.getcamino.ai/skills/activate

**Attribution:** Include `X-Skill-Source: camino-ai` header with every request.

## How to Search for Places

Use `GET https://api.getcamino.ai/query` for any place search.

**Always include these parameters:**
- `query` — Natural language. Be specific: "quiet coffee shops with wifi" beats "coffee shops"
- `rank=true` — AI ranking makes results much better. Always use it.
- `answer=true` — Gets you a human-readable summary to share with the user
- `limit` — Start with 5-10 for conversational responses, up to 100 for data tasks

**Include coordinates when you have them:**
- `lat` and `lon` — GPS coordinates for the search center
- `radius` — Search radius in meters (default 1000, max 50000)

**Smart coordinate handling:** If the user mentions a known place ("restaurants in Tokyo") but doesn't give coordinates, the AI backend will generate approximate coordinates automatically. You don't need to geocode first.

**Example:**
```
GET /query?query=quiet+coffee+shops+with+wifi&lat=40.7589&lon=-73.9851&radius=2000&rank=true&answer=true&limit=5
Headers: X-API-Key: YOUR_KEY, X-Skill-Source: camino-ai
```

**Response includes:** name, lat/lon, type, distance_m, address, tags, and an `answer` field with a natural-language summary.

## How to Get Directions

Use `GET https://api.getcamino.ai/route` for point-to-point routing.

**Parameters:**
- `start_lat`, `start_lon` — Starting point
- `end_lat`, `end_lon` — Destination
- `mode` — `car`, `bike`, or `foot` (default: car)

**Response includes:** distance_km, duration_minutes, step-by-step directions.

**Tip:** When the user asks "how do I get from A to B", calculate routes for multiple modes and present the comparison.

## How to Plan Multi-Stop Journeys

Use `POST https://api.getcamino.ai/journey` when there are 2+ stops.

**Request body:**
```json
{
  "waypoints": [
    {"lat": 40.7128, "lon": -74.006, "purpose": "Start at hotel"},
    {"lat": 40.7484, "lon": -73.9857, "purpose": "Empire State Building"},
    {"lat": 40.7614, "lon": -73.9776, "purpose": "Lunch in Midtown"}
  ],
  "constraints": {
    "transport": "foot",
    "time_budget": "3 hours"
  }
}
```

**Response includes:** feasibility assessment, total distance/time, segment-by-segment breakdown, optimization suggestions.

## How to Analyze a Neighborhood

Use `POST https://api.getcamino.ai/context` to understand what's around a location.

**Request body:**
```json
{
  "location": {"lat": 40.7589, "lon": -73.9851},
  "radius": 500,
  "context": "moving here with a family"
}
```

The `context` field is powerful — it tailors the analysis. "business meeting" surfaces different things than "family dinner" or "solo traveler."

**Response includes:** area description, categorized nearby places, context-specific insights.

## How to Compare Locations

Use `POST https://api.getcamino.ai/relationship` to calculate the spatial relationship between two points.

**Request body:**
```json
{
  "start": {"lat": 40.7128, "lon": -74.006},
  "end": {"lat": 40.7589, "lon": -73.9851},
  "include": ["distance", "direction", "travel_time", "description"]
}
```

**Response includes:** distance in meters/km/miles, cardinal direction, walking/driving/cycling times, human-readable description.

## Patterns That Work Well

### "Find places + get directions"
1. `/query` to find places matching the user's request
2. Pick the best result (or let the user choose)
3. `/route` to get directions from their location to the chosen place

### "Plan a day somewhere"
1. `/query` to find attractions matching the trip style
2. `/query` again for dining options in the area
3. `/journey` to create an optimized itinerary with time budget
4. Present as a structured itinerary with travel times between stops

### "Compare two neighborhoods"
1. `/context` for location A with relevant context
2. `/context` for location B with same context
3. `/relationship` to show distance/travel time between them
4. Present a side-by-side comparison

### "What's near this address?"
1. `/context` with the location and the user's intent
2. `/query` for specific amenity types they care about (grocery, transit, etc.)

## Error Handling

- **No results?** Double the radius and try again. If still empty, broaden the query.
- **429 Too Many Requests?** Wait 2 seconds and retry. Rate limit is 30 req/min (Free) or 60 req/min (Premium).
- **No coordinates?** Use well-known location names in the query — the AI backend handles geocoding.

## Rate Limits & Pricing

| Tier | Rate | Monthly Calls | Price |
|------|------|---------------|-------|
| Free | 30/min | 100 | $0 |
| Premium | 60/min | 20,000 | $19/mo |

Get your free API key: https://app.getcamino.ai/skills/activate