Ultimaps MCP

API карт изображений

Данные на входе, изображение карты на выходе. Один URL отображает хороплетную, категорийную или точечную карту любой страны, штата, округа или ZIP-зоны в формате PNG. Без аккаунта, без ключа, без картографической библиотеки в вашем стеке.

https://api.ultimaps.com/v1/renders?spec=%7B%22mapId%22%3A%22united-states%22%2C%22regions%22%3A%7B%22US-CA%22%3A%22%231D4ED8%22%2C%22US-TX%22%3A%22%23F59E0B%22%2C%22New%20York%22%3A%22%2310B981%22%7D%2C%22title%22%3A%7B%22text%22%3A%22Where%20we%20operate%22%7D%2C%22style%22%3A%7B%22labels%22%3A%7B%22show%22%3Atrue%7D%7D%2C%22output%22%3A%7B%22width%22%3A1200%7D%7D

Это весь запрос. Параметр spec — это JSON в URL-кодировке, а ответ — само изображение.

Отображается в реальном времени по URL слева, кэшируется на 24 часа.

Встраивается куда угодно

URL возвращает изображение, поэтому оно работает в теге <img>, в README, на странице Notion или в ячейке Google Sheets.

GET или POST

GET принимает все функции, но ограничивает спецификацию 6 КБ и всегда отображает PNG без ключа размером до 1600 пикселей. Отправьте тот же JSON в POST /v1/renders для большего объема данных, ключ для большего холста или Pro-ключ для SVG.

Редактирование после создания

Каждое изображение несет заголовок Link, который открывает рендер в Ultimaps Studio как настоящую карту. Рендеры без ключа открываются для любого, у кого есть ссылка. Рендер с ключом открывается только для того, кто вошел в рабочее пространство этого ключа.

Поваренная книга

Шесть полных запросов. Каждый проверяется на соответствие актуальной схеме запросов в CI, поэтому вы можете копировать их как есть, менять mapId и значения — и работать. Каждое изображение — это ответ на запрос рядом с ним, включая водяной знак, на бесплатном тарифе без ключа.

Выделение нескольких регионов

Самый простой полезный запрос. Вы называете регионы и задаете каждому цвет. Все остальное использует значения по умолчанию.

{
  "mapId": "united-states",
  "regions": {
    "US-CA": "#1D4ED8",
    "US-TX": "#F59E0B",
    "New York": "#10B981"
  },
  "title": {
    "text": "Where we operate"
  },
  "style": {
    "labels": {
      "show": true
    }
  },
  "output": {
    "width": 1200
  }
}

curl https://api.ultimaps.com/v1/renders \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "regions": {
      "US-CA": "#1D4ED8",
      "US-TX": "#F59E0B",
      "New York": "#10B981"
    },
    "title": {
      "text": "Where we operate"
    },
    "style": {
      "labels": {
        "show": true
      }
    },
    "output": {
      "width": 1200
    }
  }' \
  -o map.png

Карта Соединенных Штатов с заголовком «Где мы работаем», с Калифорнией синим, Техасом оранжевым и Нью-Йорком зеленым, все остальные штаты в теме по умолчанию и с подписями их аббревиатур

• Ключи регионов гибкие. «US-CA», «California» и «CA» ведут к одному и тому же региону.
• Цвета — это hex-строки. Регионы, которые вы пропустили, сохраняют тему по умолчанию.
• «style.labels.show» выводит названия всех регионов. Невозможно подписать только те регионы, которые вы раскрасили.

Открыть этот рендер в новой вкладке

Хороплет из чисел

Передайте API необработанные значения, и он выберет классы, цвета и легенду. Это запрос, который нужен большинству людей.

{
  "mapId": "united-states",
  "choropleth": {
    "values": {
      "California": 39.5,
      "Texas": 30.5,
      "Florida": 22.6,
      "New York": 19.6,
      "Pennsylvania": 13,
      "Illinois": 12.5,
      "Ohio": 11.8,
      "Georgia": 11,
      "North Carolina": 10.8,
      "Michigan": 10
    },
    "type": "groups",
    "palette": "blues",
    "classes": 5,
    "method": "quantile",
    "noDataColor": "#EEEEEE",
    "format": {
      "decimals": 1,
      "suffix": "M"
    }
  },
  "legend": {
    "position": "left"
  },
  "title": {
    "text": "Population by state, 2025"
  },
  "style": {
    "labels": {
      "show": true,
      "content": "value"
    }
  },
  "output": {
    "width": 1600,
    "scale": 1
  }
}

curl https://api.ultimaps.com/v1/renders \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "choropleth": {
      "values": {
        "California": 39.5,
        "Texas": 30.5,
        "Florida": 22.6,
        "New York": 19.6,
        "Pennsylvania": 13,
        "Illinois": 12.5,
        "Ohio": 11.8,
        "Georgia": 11,
        "North Carolina": 10.8,
        "Michigan": 10
      },
      "type": "groups",
      "palette": "blues",
      "classes": 5,
      "method": "quantile",
      "noDataColor": "#EEEEEE",
      "format": {
        "decimals": 1,
        "suffix": "M"
      }
    },
    "legend": {
      "position": "left"
    },
    "title": {
      "text": "Population by state, 2025"
    },
    "style": {
      "labels": {
        "show": true,
        "content": "value"
      }
    },
    "output": {
      "width": 1600,
      "scale": 1
    }
  }' \
  -o map.png

Хороплетная карта населения штатов США в 2025 году, затененная по пяти синим квантильным классам с подписями разрывов в легенде и значениями в миллионах на каждом штате

• Опустите «type», «classes» и «method» — API определит их по вашим данным.
• «palette» принимает любую из 26 встроенных палитр. «noDataColor» закрашивает регионы, не покрытые вашими данными.
• «format» управляет подписями разрывов в легенде, а не форматом изображения.

Открыть этот рендер в новой вкладке

Точки

Маркеры широты и долготы. Точки сочетаются со всем остальным, поэтому вы можете разместить их на хороплетной или обычной карте.

Для вывода SVG нужен Pro-ключ. Опустите «format» для PNG на любом тарифе.

{
  "mapId": "united-states",
  "style": {
    "theme": "paper",
    "defaultRegionColor": "#F1F5F9"
  },
  "locations": [
    {
      "title": "Austin HQ",
      "lat": 30.2672,
      "lon": -97.7431,
      "color": "#1D4ED8"
    },
    {
      "title": "Denver",
      "lat": 39.7392,
      "lon": -104.9903,
      "labelPosition": "right"
    },
    {
      "title": "Seattle",
      "lat": 47.6062,
      "lon": -122.3321
    }
  ],
  "output": {
    "width": 1400,
    "format": "svg"
  }
}

curl https://api.ultimaps.com/v1/renders \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "style": {
      "theme": "paper",
      "defaultRegionColor": "#F1F5F9"
    },
    "locations": [
      {
        "title": "Austin HQ",
        "lat": 30.2672,
        "lon": -97.7431,
        "color": "#1D4ED8"
      },
      {
        "title": "Denver",
        "lat": 39.7392,
        "lon": -104.9903,
        "labelPosition": "right"
      },
      {
        "title": "Seattle",
        "lat": 47.6062,
        "lon": -122.3321
      }
    ],
    "output": {
      "width": 1400,
      "format": "svg"
    }
  }' \
  -o map.svg

Показано как PNG — запрос запрашивает SVG. Карта в любом случае одинаковая.

• Каждая точка имеет свой цвет, сторону подписи и видимость подписи.
• Точки размещаются по координатам. API не геокодирует адреса.

Для SVG нужен Pro-ключ. Путь GET без ключа возвращает только PNG.

Проверка запроса перед рендером

Сухой прогон возвращает JSON вместо изображения: какие ключи совпали, какие нет, что было исправлено и какие получились разрывы. Это не расходует квоту.

{
  "mapId": "united-states",
  "choropleth": {
    "values": {
      "Calfornia": 39.5,
      "Texas": 30.5,
      "Florida": 22.6,
      "Atlantis": 1
    }
  },
  "dryRun": true
}

curl https://api.ultimaps.com/v1/renders \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "choropleth": {
      "values": {
        "Calfornia": 39.5,
        "Texas": 30.5,
        "Florida": 22.6,
        "Atlantis": 1
      }
    },
    "dryRun": true
  }'

• Опечатка «Calfornia» возвращается исправленной на California. «Atlantis» возвращается как несовпавший.
• Используйте это при подключении данных, затем отключите «dryRun».

Открыть JSON сухого прогона, который возвращается

Ошибка при неверных ключах вместо угадывания

По умолчанию несовпавшие ключи пропускаются. Установите «onUnmatched» в «error», и API вернет 400 с предложениями по каждому ключу — это то, что нужно в запланированном задании.

{
  "mapId": "united-states",
  "choropleth": {
    "values": {
      "California": 39.5,
      "Texassss": 30.5,
      "Atlantis": 1
    }
  },
  "onUnmatched": "error"
}

curl https://api.ultimaps.com/v1/renders \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "choropleth": {
      "values": {
        "California": 39.5,
        "Texassss": 30.5,
        "Atlantis": 1
      }
    },
    "onUnmatched": "error"
  }' \
  -o map.png

• Ошибка 400 — это документ проблемы RFC 9457. Ветвитесь по «code», а не по сообщению.

Открыть 400, который возвращается

Полный справочник полей, включая все 26 палитр, четыре метода разрывов, темы, дополнительные слои и форматирование чисел: справочник API.

Карты, которые можно отобразить

187 карт: от карт мира и континентов до округов США и ZIP-зон. mapId — это слаг карты на этом сайте, и он никогда не меняется после публикации.

united-states-canada france-departments india europe canada united-states united-arab-emirates united-kingdom-counties world

Ключи и лимиты

Ключ повышает лимиты скорости и размер холста. Pro-ключ убирает водяной знак и открывает SVG. Создайте его в Studio в разделе Workspace, затем API. Ключи показываются один раз.

curl https://api.ultimaps.com/v1/renders \
  -H "Authorization: Bearer $ULTIMAPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mapId": "united-states",
    "choropleth": {
      "values": {
        "California": 39.5,
        "Texas": 30.5,
        "Florida": 22.6,
        "New York": 19.6,
        "Pennsylvania": 13,
        "Illinois": 12.5,
        "Ohio": 11.8,
        "Georgia": 11,
        "North Carolina": 10.8,
        "Michigan": 10
      },
      "type": "groups",
      "palette": "blues",
      "classes": 5,
      "method": "quantile",
      "noDataColor": "#EEEEEE",
      "format": {
        "decimals": 1,
        "suffix": "M"
      }
    },
    "legend": {
      "position": "left"
    },
    "title": {
      "text": "Population by state, 2025"
    },
    "style": {
      "labels": {
        "show": true,
        "content": "value"
      }
    },
    "output": {
      "width": 1600,
      "scale": 1
    }
  }' \
  -o map.png

Тариф	Аутентификация	Форматы	Атрибуция	Холст	Лимит скорости	Месячный лимит
Без ключа	нет	PNG	полный водяной знак	≤ 1600 px, масштаб 1	30/час на IP, всплеск 5/мин	без месячного лимита
Бесплатный ключ	Bearer um_live_…	PNG	полный водяной знак	≤ 1600 px, масштаб ≤ 2	10/мин, 50/день	500 рендеров
Pro-ключ	Bearer um_live_…	PNG, SVG	нет	≤ 4000 px, масштаб ≤ 4	30/мин, 1,000/день	5,000 рендеров

Месячная квота — это состояние биллинга и возвращает 402, никогда не повторяется. Лимиты скорости и параллелизма возвращают 429 с Retry-After. Сухие прогоны никогда не расходуют квоту. Проверьте GET /v1/usage, чтобы узнать свое положение.

Из Claude, Codex или любого MCP-клиента

Попросите карту в чате — и изображение вернется в разговор. @ultimaps/mcp — это этот API в виде MCP-инструментов через stdio, без аккаунта: render_map, list_maps и get_map_regions.

claude mcp add ultimaps -- npx -y @ultimaps/mcp
codex mcp add ultimaps -- npx -y @ultimaps/mcp

Клиенты, которые читают файл конфигурации, принимают те же два значения. Это claude_desktop_config.json.

{
  "mcpServers": {
    "ultimaps": {
      "command": "npx",
      "args": ["-y", "@ultimaps/mcp"],
      "env": { "ULTIMAPS_API_KEY": "" }
    }
  }
}

Оставьте ULTIMAPS_API_KEY пустым для тарифа без ключа — те же лимиты, что в таблице выше, или заполните его для квоты и вывода вашего плана.

Не в v1

v1 отображает изображения. Он не делает следующего:

• Публикация интерактивных или встраиваемых карт
• Вывод в PDF
• Геокодирование адресов в координаты
• Чтение геометрии, лежащей в основе карты

Если вам нужно что-то из этого, скажите нам, что именно, и мы сообщим, когда это появится. То, о чем просят люди, — это то, что мы строим дальше.

Справочник

Справочник API

Каждая конечная точка и поле, в реальном времени против работающего API.

Коды ошибок

Каждый код, его HTTP-статус и нужно ли повторять запрос.

openapi.json

Контракт OpenAPI 3.1. Сгенерируйте клиент из него.

llms-full.txt

Весь API одним текстовым файлом для агентов кодирования.

@ultimaps/mcp

MCP-сервер. Три инструмента, stdio, без аккаунта.

Часто задаваемые вопросы

Есть ли API хороплетных карт?

Да, это основная функция этого API. Отправьте набор ключей регионов и чисел — и получите классифицированную, раскрашенную карту с легендой в формате PNG. API выбирает метод разрывов, количество классов и палитру из ваших данных, если вы не зададите их сами.

Как сгенерировать изображение карты из URL?

Поместите JSON запроса в параметр spec запроса GET /v1/renders — и ответом будет сам PNG. Этот URL работает в теге img, в markdown-изображении, в блоке изображения Notion или в формуле IMAGE() Google Sheets, без ключа и без аккаунта.

Можно ли использовать API карт изображений без ключа?

Да. Тариф без ключа отображает PNG до 1600 на 1600 пикселей при 30 рендерах в час на IP, с водяным знаком Ultimaps. Ключ повышает лимиты, а Pro-ключ убирает водяной знак и добавляет SVG.

Это API карт округов? Можно ли получить границы округов?

Он отображает карты округов как изображения, включая все 3 143 округа США, но не предоставляет геометрию границ. Если вам нужны GeoJSON или шейп-файлы для собственной обработки, используйте Census TIGER или Natural Earth. Этот API возвращает картинки.

Геокодирует ли он адреса?

Нет. Точки размещаются по широте и долготе, а цвета регионов сопоставляются по ключу или названию региона. Геокодирование — это функция Studio, а не API.

Есть ли MCP-сервер?

Да. Установите @ultimaps/mcp в Claude Code, Codex, Claude Desktop, Cursor, VS Code или любой другой MCP-клиент — и он предоставит render_map, list_maps и get_map_regions через stdio. Он работает на Node.js 20 или новее, не требует аккаунта и читает ULTIMAPS_API_KEY, если вы его задали.

Можно ли получить SVG вместо PNG?

Да, с Pro-ключом. Установите output.format в svg. Тарифы без ключа и с бесплатным ключом возвращают PNG.

Что будет, если названия моих регионов не совпадут?

Ключи сопоставляются без учета регистра с кодами регионов, названиями, распространенными псевдонимами и нормализованными названиями, поэтому US-CA, California и CA ведут к одному региону, а однозначные опечатки исправляются и сообщаются. По умолчанию несовпавшие ключи пропускаются и сообщаются в заголовке ответа. Установите onUnmatched в error — и запрос завершится ошибкой с предложениями по каждому ключу.

Как поместить карту в README на GitHub?

Используйте URL GET без ключа как markdown-изображение. GitHub проксирует его через Camo, и поскольку API отправляет заголовок кэша на 24 часа, изображение обновляется ежедневно, а не замораживается.

Можно ли отобразить карту на серверной стороне?

Да. Каждый рендер происходит на наших серверах, поэтому в вашем стеке нет браузера, headless Chrome или картографической библиотеки. Один HTTP-вызов возвращает готовое изображение.