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 px. Отправьте тот же 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

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

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

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

Картограмма из чисел

Передайте 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",
    "noData": true,
    "format": {
      "decimals": 1,
      "suffix": "M"
    }
  },
  "legend": {
    "position": "left",
    "title": "Population (millions)"
  },
  "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",
      "noData": true,
      "format": {
        "decimals": 1,
        "suffix": "M"
      }
    },
    "legend": {
      "position": "left",
      "title": "Population (millions)"
    },
    "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» закрашивает регионы, не покрытые вашими данными, а «noData» добавляет для них строку «No data» в легенду.
• «legend.title» называет, что измеряют цвета. Давайте каждой легенде данных заголовок.
• «format» управляет тем, как числа печатаются в легенде и на карте, а не форматом изображения.
• «style.labels.content» здесь равен «value». «name_value» печатает название штата с числом под ним.

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

Маркеры

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

Для вывода 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.

Карты, которые можно отрисовать

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

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

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

Ключ повышает лимиты частоты и размер холста. 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",
      "noData": true,
      "format": {
        "decimals": 1,
        "suffix": "M"
      }
    },
    "legend": {
      "position": "left",
      "title": "Population (millions)"
    },
    "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, чтобы узнать, где вы находитесь.

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

Используйте этот API из ChatGPT, Claude, Cursor или любого MCP-клиента и получайте карту прямо в чате. Добавьте https://api.ultimaps.com/mcp по URL или запустите пакет @ultimaps/mcp на своём компьютере. Ни то, ни другое не требует аккаунта.

Настроить сервер Ultimaps MCP

Чего нет в v1

v1 отрисовывает изображения. Он не делает ничего из этого:

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

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

Справочник

Справочник API

Каждый эндпоинт и поле, вживую против работающего API.

Коды ошибок

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

openapi.json

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

llms-full.txt

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

MCP-сервер

Добавьте https://api.ultimaps.com/mcp по URL или запустите @ultimaps/mcp локально. Аккаунт не нужен.

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

Есть ли API картограмм?

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

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

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

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

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

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

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

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

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

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

Да. Добавьте https://api.ultimaps.com/mcp по URL в ChatGPT, Claude или любом MCP-клиенте или запустите пакет @ultimaps/mcp локально, и ваш ассистент получит render_map, list_maps и get_map_regions без необходимости в аккаунте. Шаги настройки для каждого клиента — на ultimaps.com/mcp/.

Можно ли получить 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-вызов возвращает готовое изображение.