Ultimaps MCP

공식

데이터를 지도 이미지로 변환: 세계, 국가, 주, 카운티 및 우편번호의 코로플레스 지도, 카테고리 지도, 핀 지도.

ultimaps.com에서 보기이 MCP 사용해 보기스폰서

Ultimaps MCP(으)로 무엇을 할 수 있나요?

  • Render choropleth maps — 숫자 값으로 색칠된 지도를 요청하면 범례와 라벨이 포함된 분류된 PNG를 받을 수 있습니다.
  • 특정 지역 강조 — "우리가 운영하는 곳"처럼 명명된 주, 카운티 또는 우편번호를 사용자 지정 색상으로 채운 지도를 요청할 수 있습니다.
  • 위치 핀 추가 — 모든 지도에 사용자 지정 제목, 색상 및 라벨 위치를 가진 위도/경도 마커를 표시할 수 있습니다.
  • 지도 데이터 검증 — 드라이 런을 실행하여 어떤 지역 키가 일치하는지 확인하고, 오타 수정을 받고, 렌더링 전에 분할 값을 확인할 수 있습니다.
  • 사용 가능한 지도 목록 — list_maps를 통해 187개 지도(국가, 주, 카운티, 우편번호 지역) 중 어떤 것이 사용 가능한지 물어볼 수 있습니다.
  • 지역 식별자 가져오기 — get_map_regions를 사용하여 렌더링 요청에 사용할 지도 지역의 정확한 키 또는 이름을 조회할 수 있습니다.

문서

Map Image API

데이터를 넣으면 지도 이미지가 나옵니다. 하나의 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 Sheets 셀에서도 작동합니다.

GET 또는 POST

GET은 모든 기능을 지원하지만 사양을 6KB로 제한하며, 항상 최대 1600px의 키 없는 PNG를 렌더링합니다. 동일한 JSON을 POST /v1/renders에 보내면 더 큰 페이로드, 더 큰 캔버스용 키 또는 SVG용 Pro 키를 사용할 수 있습니다.

이후에도 편집 가능

모든 이미지에는 Ultimaps Studio에서 렌더링을 실제 지도로 여는 Link 헤더가 포함됩니다. 키 없는 렌더링은 링크가 있는 모든 사람에게 열립니다. 키가 있는 렌더링은 해당 키의 워크스페이스에 로그인한 사람에게만 열립니다.

쿡북

완전한 요청 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, 배율 ≤ 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는 계정 없이 stdio를 통한 MCP 도구로 제공되는 이 API입니다: 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에서 지도 이미지를 어떻게 생성하나요?

GET /v1/renders의 spec 쿼리 매개변수에 요청 JSON을 넣으면 응답이 PNG 자체입니다. 해당 URL은 키와 계정 없이 img 태그, 마크다운 이미지, Notion 이미지 블록 또는 Google Sheets IMAGE() 수식에서 작동합니다.

API 키 없이 지도 이미지 API를 사용할 수 있나요?

네. 키 없는 티어는 IP당 시간당 30회 렌더링으로 최대 1600x1600 픽셀의 PNG를 렌더링하며 Ultimaps 워터마크가 포함됩니다. 키는 제한을 높이고 Pro 키는 워터마크를 제거하며 SVG를 추가합니다.

카운티 지도 API인가요? 카운티 경계를 얻을 수 있나요?

이미지로 카운티 지도를 렌더링하며 미국의 3,143개 카운티를 모두 포함하지만 경계 지오메트리는 제공하지 않습니다. 직접 처리할 GeoJSON이나 shapefile이 필요하면 Census TIGER 또는 Natural Earth를 사용하세요. 이 API는 그림을 반환합니다.

주소를 지오코딩하나요?

아니요. 핀은 위도와 경도로 배치되고 지역 색상은 지역 키 또는 이름으로 일치됩니다. 지오코딩은 API 기능이 아닌 Studio 기능입니다.

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 호출로 완성된 이미지를 반환합니다.