Ultimaps MCP

公式

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

ultimaps.com で表示このMCPを試すスポンサー

Ultimaps MCPで何ができますか？

  • Render choropleth maps — 数値で色分けされた地図をリクエストすると、凡例とラベル付きの分類済みPNGが得られます。
  • Highlight specific regions — 指定した州、郡、またはZIPコードをカスタム色で塗りつぶした地図をリクエストできます（例：「当社の事業エリア」）。
  • Add location pins — 任意の地図上に、カスタムタイトル、色、ラベル位置を指定した緯度・経度マーカーをプロットできます。
  • Validate map data — ドライランを実行して、どの地域キーが一致するかを確認し、タイプミスの修正や、レンダリング前の区切り値を確認できます。
  • List available maps — 187種類の地図（国、州、郡、ZIPエリア）のうちどれが利用可能かを、list_maps を使って確認できます。
  • Get region identifiers — レンダリングリクエストで使用するために、地図の地域の正確なキーや名前を get_map_regions で検索できます。

ドキュメント

マップ画像API

データを入れると、マップ画像が出てきます。1つのURLで、任意の国・州・郡・郵便番号エリアのコロプレスマップ、カテゴリマップ、ピンマップを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はすべての機能を利用できますが、スペックは6KBに制限され、常にキーレスで最大1600pxのPNGをレンダリングします。同じ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 labelled with its abbreviation

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

  • リージョンキーは柔軟です。「US-CA」「California」「CA」はすべて同じ地域に到達します。
  • 色は16進数の文字列です。指定しなかった地域はテーマのデフォルトを維持します。
  • 「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

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」はデータがカバーしない地域を塗りつぶします。
  • 「format」は凡例の区切りラベルを制御するもので、画像形式を制御するものではありません。

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

ピン

緯度と経度のマーカーです。ピンは他のすべての要素と合成できるので、コロプレスマップやプレーンなマップの上にドロップできます。

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 labelled 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リファレンス。

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

187のマップ。世界地図や大陸地図から、米国の郡や郵便番号エリアまで。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、スケール1IPあたり30/時間、バースト5/分月間上限なし
フリーキーBearer um_live_…PNG完全な透かし≤ 1600 px、スケール ≤ 210/分、50/日500レンダリング
ProキーBearer um_live_…PNG、SVGなし≤ 4000 px、スケール ≤ 430/分、1,000/日5,000レンダリング

月間クォータは請求状態であり、402 を返します。再試行はできません。レートと同時実行数の制限は、Retry-After 付きで 429 を返します。ドライランはクォータを消費しません。現在の状況は GET /v1/usage で確認できます。

Claude、Codex、または任意のMCPクライアントから

チャットでマップを依頼すると、画像が会話に返ってきます。@ultimaps/mcp は、このAPIをstdio上のMCPツールとして提供するもので、アカウントは不要です：render_map、list_maps、get_map_regions。

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

設定ファイルを読み取るクライアントは、同じ2つの値を使用します。これは 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全体を1つのプレーンテキストファイルとして、コーディングエージェント向けに提供。

@ultimaps/mcp

MCPサーバー。3つのツール、stdio、アカウント不要。

よくある質問

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

はい、それがこのAPIの主な機能です。リージョンキーと数値のセットを投稿すると、分類・色分け・凡例付きのマップがPNGとして返ってきます。ブレークメソッド、クラス数、パレットは、自分で設定しない限り、APIがデータから自動選択します。

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

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

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

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

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

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

住所をジオコーディングしますか？

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

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

はい。Claude Code、Codex、Claude Desktop、Cursor、VS Code、またはその他のMCPクライアントに @ultimaps/mcp をインストールすると、stdio上で render_map、list_maps、get_map_regions を公開します。Node.js 20以降で動作し、アカウントは不要で、設定すると ULTIMAPS_API_KEY を読み取ります。

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

はい、Proキーがあれば可能です。output.format を svg に設定します。キーレスとフリーキーはPNGを返します。

リージョン名が一致しない場合はどうなりますか？

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

GitHub READMEにマップを置くにはどうすればいいですか？

キーレスのGET URLをマークダウン画像として使用します。GitHubはCamoを通じてプロキシし、APIが24時間のキャッシュヘッダーを送信するため、画像はフリーズせずに毎日更新されます。

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

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