---
name: maps
description: Manage NiftyImages maps and map locations through the v2 API. Use when a user asks an agent to find map ids, inspect map metadata, update map settings, search locations by address, unique id, or proximity, add locations, update locations, delete locations, or explain how map image ids work.
---

# Maps

Use this skill to work with NiftyImages maps and their locations.

## API Context

- Base URL: `https://dev.niftyimages.com/v2`
- OpenAPI: `https://dev.niftyimages.com/openapi/v1.json`
- Guide: `https://dev.niftyimages.com/docs/maps.md`
- Related guide: `https://dev.niftyimages.com/docs/images.md`
- Auth: `Authorization: Bearer {apiKey}`

## Credential Rules

- If the user wants live API calls and no NiftyImages API key is available, ask for one before calling `/v2`.
- If the user only wants planning or code generation, continue without an API key.
- Never invent, guess, log, or expose the API key.

## Core Contract

A map is an image with the `map` image type. `mapId` in `/v2/maps/...` is the image id returned by `GET /v2/images?type=map`, not the internal NiftyMap GUID.

Unknown maps, wrong-type images, and cross-account maps return `404`.

## Workflow

1. If `mapId` is missing, list map images with `GET /v2/images?type=map`.
2. Preserve the returned image id and use it as `mapId`.
3. Fetch map metadata with `GET /v2/maps/{mapId}` when settings or location counts are needed.
4. Use one location search mode at a time:
   - `address={text}`
   - `uniqueId={id}`
   - `lat={latitude}&lng={longitude}` with optional `radiusMiles`
5. Preserve `mapId`, `locationId`, and cursor values exactly as returned.
6. Summarize location results in human language and include raw ids when useful.

## Operations

- Update map settings: `PATCH /v2/maps/{mapId}` with `name`, `searchRadiusMiles`, or `maxResults`.
- List/search locations: `GET /v2/maps/{mapId}/locations`.
- Get a location: `GET /v2/maps/{mapId}/locations/{locationId}`.
- Add a location: `POST /v2/maps/{mapId}/locations`.
- Update a location: `PATCH /v2/maps/{mapId}/locations/{locationId}`.
- Delete a location: `DELETE /v2/maps/{mapId}/locations/{locationId}`.

## Location Rules

- Add a location with either `address` or `lat` plus `lng`.
- Address-based writes are queued for geocoding.
- Updating an address without explicit coordinates re-queues geocoding.
- Use `uniqueId` when the caller needs stable external lookup.
- Use `properties` for caller-defined metadata such as store name, region, or status.

## Safety Rules

- Ask for confirmation before deleting locations when user intent is ambiguous.
- Explain that location delete is a hard delete when relevant.
- Do not pass more than one search filter mode in a single location search.
- Do not construct map image ids from internal map ids.
- Do not expose API keys in copied examples or URLs.