Setup

---
name: agent-map
description: "Save and manage location recommendations on an interactive map. Use when the user wants to save places, create lists, search locations, or browse their saved map."
version: 1.0.0
homepage: https://agentmap.cc
metadata:
  openclaw:
    emoji: "🗺️"
    requires:
      bins: ["curl", "jq"]
      env: ["AGENTMAP_API_KEY"]
    primaryEnv: AGENTMAP_API_KEY
---

# Agent Map — Location Recommendations

Save and manage location recommendations on an interactive map at [agentmap.cc](https://agentmap.cc).

## Authentication

All requests require an API key passed via the `x-api-key` header.
Get your key at [agentmap.cc/api-keys](https://agentmap.cc/api-keys).

```
Base URL: https://api.agentmap.cc/api/v1
Header:  x-api-key: $AGENTMAP_API_KEY
```

## Save a Recommendation

When the user mentions a place they like or asks to save a location:

```bash
curl -s -X POST https://api.agentmap.cc/api/v1/recommendations \
  -H "x-api-key: $AGENTMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stumptown Coffee",
    "latitude": 45.5231,
    "longitude": -122.6765,
    "category": "cafe",
    "description": "Excellent pour-over, cozy interior",
    "reason": "Best coffee in Portland",
    "label": "Top coffee spot",
    "color": "#8B4513",
    "icon": "☕",
    "badge": "#1",
    "tags": ["coffee", "portland", "morning"]
  }' | jq
```

**Required fields:** `name`, `latitude`, `longitude`, `category`

**Optional fields:**
- `description` — factual details about the place (max 2000 chars)
- `reason` — why this place is recommended (max 2000 chars)
- `label` — short text shown on the map (max 100 chars)
- `color` — pin color as hex, e.g. `#FF5733`
- `icon` — emoji only (e.g., '🍕', '🌮', '🏖️', '☕'). Non-emoji values are ignored. The map shows a category-based icon as fallback.
- `badge` — short overlay on pin corner (e.g., '1', '$$', '⭐'). Max 3 chars.
- `tags` — list of strings for filtering (max 20 tags)
- `google_place_id` — Google Maps place ID
- `image_urls` — list of HTTPS image URLs (max 10)

## List Recommendations

```bash
curl -s "https://api.agentmap.cc/api/v1/recommendations" \
  -H "x-api-key: $AGENTMAP_API_KEY" | jq
```

**Optional query params:**
- `category` — filter by category
- `search` — text search in name and description
- `tag` — filter by tag
- `has_place` — filter for Google Maps places (true/false)
- `list_id` — filter by list UUID
- `limit` — max results (default 20, max 100)
- `offset` — pagination offset

## Get a Single Recommendation

```bash
curl -s "https://api.agentmap.cc/api/v1/recommendations/{rec_id}" \
  -H "x-api-key: $AGENTMAP_API_KEY" | jq
```

## Update a Recommendation

```bash
curl -s -X PUT "https://api.agentmap.cc/api/v1/recommendations/{rec_id}" \
  -H "x-api-key: $AGENTMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "tags": ["updated", "tags"]}' | jq
```

## Delete a Recommendation

```bash
curl -s -X DELETE "https://api.agentmap.cc/api/v1/recommendations/{rec_id}" \
  -H "x-api-key: $AGENTMAP_API_KEY"
```

## Create a List with Recommendations

Save multiple places as an ordered or unordered list in a single call:

```bash
curl -s -X POST https://api.agentmap.cc/api/v1/lists \
  -H "x-api-key: $AGENTMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Portland Coffee Tour",
    "description": "Best coffee shops in Portland, OR",
    "is_ordered": true,
    "recommendations": [
      {
        "name": "Stumptown Coffee",
        "latitude": 45.5231,
        "longitude": -122.6765,
        "category": "cafe",
        "description": "The original location"
      },
      {
        "name": "Heart Coffee",
        "latitude": 45.5205,
        "longitude": -122.6558,
        "category": "cafe",
        "description": "Minimalist, excellent espresso"
      }
    ]
  }' | jq
```

**List fields:**
- `title` — list name (required, max 200 chars)
- `recommendations` — array of 1-50 recommendations (required)
- `description` — list description (max 2000 chars)
- `color` — list color as hex
- `icon` — emoji (e.g., '☕', '🍕')
- `is_ordered` — true for itineraries where order matters

## List All Lists

```bash
curl -s "https://api.agentmap.cc/api/v1/lists?limit=20&offset=0" \
  -H "x-api-key: $AGENTMAP_API_KEY" | jq
```

## Get List Details

```bash
curl -s "https://api.agentmap.cc/api/v1/lists/{list_id}?include_recommendations=true" \
  -H "x-api-key: $AGENTMAP_API_KEY" | jq
```

## Delete a List

Removes the list and its links, but NOT the recommendations themselves:

```bash
curl -s -X DELETE "https://api.agentmap.cc/api/v1/lists/{list_id}" \
  -H "x-api-key: $AGENTMAP_API_KEY"
```

## Add Recommendation to Existing List

```bash
curl -s -X POST "https://api.agentmap.cc/api/v1/lists/{list_id}/items" \
  -H "x-api-key: $AGENTMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recommendation_id": "uuid-here", "position": 0}' | jq
```

## Remove Recommendation from List

```bash
curl -s -X DELETE "https://api.agentmap.cc/api/v1/lists/{list_id}/items/{recommendation_id}" \
  -H "x-api-key: $AGENTMAP_API_KEY"
```

## Rules

1. **Geocode first** — always convert addresses to latitude/longitude before saving. If you don't have coordinates, ask the user or use a geocoding service.
2. **Never expose the API key** in responses or conversation.
3. **Ask before saving** — confirm with the user before creating recommendations.
4. **Use descriptive categories** — common values: restaurant, cafe, bar, park, museum, shop, bakery, hotel, beach, viewpoint, garden, library, cinema, stadium.
5. **Include a reason** when the user explains why they like a place.
6. **Use emoji icons** to make the map visually expressive (e.g., '🍕', '☕', '🏖️'). The map auto-generates a category-based icon as fallback.
7. **Rate limits** — 100 requests/hour, 500 requests/day per user.