Ultimaps MCP

公式

データを地図画像に変換：世界、国、州、郡、郵便番号のコロプレス地図、カテゴリ地図、ピンマップ。

ultimaps.com で表示

Ultimaps MCPで何ができますか？

  • データから地図をレンダリング — 地域の値を、凡例とタイトル付きの色分けされたコロプレス地図画像に変換するようアシスタントに依頼します。
  • 特定の地域をハイライト — 指定した州、郡、国を選択した16進カラーで塗りつぶした地図をリクエストします。
  • 座標でピンを配置 — 指定した緯度と経度にラベル付きのピンを配置するよう依頼します。オプションでコロプレス地図と組み合わせることもできます。
  • 利用可能な地図を一覧表示 — united-states や europe など、どのマップIDが存在するかをアシスタントに調べさせます。
  • レンダリング前に地域キーを確認 — ドライランを実行して、どの地域名が一致したか、どの地域名が修正されたか、どれが失敗したかを確認します。
  • 地図の地域を検索 — 指定した地図に含まれる地域を尋ねて、レンダリング用の有効なキーを構築できるようにします。

ドキュメント

マップ画像 API

データを渡すと、マップ画像が返ってきます。1 つの 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 パラメータは URL エンコードされた JSON で、レスポンスは画像そのものです。

US map rendered by the Ultimaps API, every state labelled, with California, Texas and New York filled in

左の URL によってライブでレンダリングされ、24 時間キャッシュされます。

どこにでも埋め込める

URL が画像を返すので、<img> タグ、README、Notion ページ、Google スプレッドシートのセルで動作します。

GET または POST

GET はすべての機能を利用できますが、spec は 6KB までに制限され、常にキー不要の PNG を最大 1600px でレンダリングします。同じ JSON を POST /v1/renders に送ると、より大きなペイロード、より大きなキャンバス用のキー、または SVG 用の Pro キーを利用できます。

後から編集可能

すべての画像には Link ヘッダーが付いており、Ultimaps Studio で実際のマップとしてレンダリングを開けます。キー不要のレンダリングはリンクを知っている人なら誰でも開けます。キー付きのレンダリングは、そのキーのワークスペースにサインインしている人だけが開けます。

クックブック

6 つの完全なリクエスト。いずれも 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

Map of the United States titled "Where we operate", with California blue, Texas orange and New York green, every other state in the theme default and labeled with its abbreviation

「Where we operate」というタイトルのアメリカ合衆国のマップ。カリフォルニアが青、テキサスがオレンジ、ニューヨークが緑で、それ以外の州はテーマのデフォルト色で略称がラベル表示されている

  • 地域キーは柔軟です。「US-CA」「California」「CA」はすべて同じ地域に到達します。
  • 色は 16 進数の文字列です。省略した地域はテーマのデフォルトのままです。
  • 「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

Choropleth map of US state population in 2025, shaded across five blue quantile classes with the break labels in a legend and each value printed in millions on its state

2025 年の米国州別人口のコロプレスマップ。5 つの青い分位クラスで塗り分けられ、凡例に区切りのラベルがあり、各値が百万単位でその州の上に表示されている

  • 「type」「classes」「method」を省略すると、API がデータから自動検出します。
  • 「palette」は 26 種類の組み込みパレットのいずれかを取ります。「noDataColor」はデータがカバーしない地域を塗り、「noData」はそれらの地域用に凡例へ「No data」行を追加します。
  • 「legend.title」は色が何を測っているかを示します。データ凡例には必ず付けてください。
  • 「format」は凡例とマップ上での数値の表示方法を制御するもので、画像フォーマットではありません。
  • ここでは「style.labels.content」は「value」です。「name_value」は州名とその下に数値を表示します。

このレンダリングを新しいタブで開く

ピン

緯度と経度のマーカーです。ピンは他のすべてと組み合わせられるので、コロプレスマップやプレーンなマップの上に配置できます。

SVG 出力には Pro キーが必要です。PNG にしたい場合はどのティアでも「format」を外してください。

{
  "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

Map of the United States on a pale theme with labeled pins on Austin, Denver and Seattle, the Austin pin in blue and the other two in the default red

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 パレット、4 つの区切り方法、テーマ、追加レイヤー、数値フォーマットを含む完全なフィールドリファレンス: API リファレンス。

レンダリングできるマップ

世界地図や大陸地図から米国の郡や ZIP コード地域まで、189 のマップがあります。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、scale 1IP あたり 30/時間、バースト 5/分月間上限なし
無料キーBearer um_live_…PNG完全なウォーターマーク≤ 1600 px、scale ≤ 210/分、50/日500 レンダリング
Pro キーBearer um_live_…PNG、SVGなし≤ 4000 px、scale ≤ 430/分、1,000/日5,000 レンダリング

月間クォータは課金状態であり、402 を返し、決してリトライ可能ではありません。レートと同時実行の制限は Retry-After とともに 429 を返します。ドライランはクォータを消費しません。現在の状況は 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 全体を 1 つのプレーンテキストファイルにまとめた、コーディングエージェント向けのファイル。

MCP サーバー

https://api.ultimaps.com/mcp を URL で追加するか、@ultimaps/mcp をローカルで実行してください。アカウントは不要です。

よくある質問

コロプレス API はありますか？

はい、それがこの API の主な機能です。地域キーと数値のセットを送ると、分類・色分け・凡例付きのマップが PNG で返ってきます。自分で設定しない限り、API がデータから区切り方法、クラス数、パレットを選びます。

URL からマップ画像を生成するにはどうすればよいですか？

リクエスト JSON を GET /v1/renders の spec クエリパラメータに入れると、レスポンスが PNG そのものです。その URL は img タグ、markdown 画像、Notion 画像ブロック、Google スプレッドシートの IMAGE() 数式で、キーもアカウントもなしで動作します。

API キーなしでマップ画像 API を使えますか？

はい。キー不要ティアは最大 1600 × 1600 ピクセルの PNG を IP あたり 1 時間 30 レンダリングで、Ultimaps のウォーターマーク付きでレンダリングします。キーは制限を引き上げ、Pro キーはウォーターマークを削除して SVG を追加します。

これは郡マップ API ですか？郡の境界を取得できますか？

郡マップを画像としてレンダリングします。米国の全 3,143 郡を含みますが、境界ジオメトリは提供しません。自分で処理するための GeoJSON やシェープファイルが必要な場合は、代わりに Census TIGER や Natural Earth を使ってください。この API は画像を返します。

住所のジオコーディングは行いますか？

いいえ。ピンは緯度と経度で配置され、地域の色は地域キーまたは名前で照合されます。ジオコーディングは Studio の機能であり、API の機能ではありません。

MCP サーバーはありますか？

はい。ChatGPT、Claude、その他の MCP クライアントで https://api.ultimaps.com/mcp を URL で追加するか、@ultimaps/mcp パッケージをローカルで実行すると、アカウント不要でアシスタントが render_map、list_maps、get_map_regions を利用できるようになります。各クライアントのセットアップ手順は ultimaps.com/mcp/ にあります。

PNG の代わりに SVG を取得できますか？

はい、Pro キーで可能です。output.format を svg に設定してください。キー不要および無料キーは PNG を返します。

地域名が一致しない場合はどうなりますか？

キーは地域コード、タイトル、一般的なエイリアス、正規化されたタイトルに対して大文字小文字を区別せずに照合されるため、US-CA、California、CA はすべて同じ地域に到達し、曖昧でないタイポは修正されて報告されます。デフォルトでは一致しないキーはスキップされ、レスポンスヘッダーで報告されます。onUnmatched を error に設定すると、代わりにキーごとの候補とともにリクエストが失敗します。

GitHub README にマップを入れるにはどうすればよいですか？

キー不要の GET URL を markdown 画像として使ってください。GitHub は Camo 経由でプロキシし、API が 24 時間のキャッシュヘッダーを送るため、画像は固定されるのではなく毎日更新されます。

サーバーサイドでマップをレンダリングできますか？

はい。すべてのレンダリングは当社のサーバーで行われるため、あなたのスタックにブラウザもヘッドレス Chrome もマップライブラリも不要です。1 回の HTTP 呼び出しで完成した画像が返ります。