raster

참고
Tile Map API 는 2020년 6월 1일 부로 서비스가 종료 됩니다. 해당 날짜 이후로는 호출이 불가 하오니, 이용에 참고 부탁 드립니다.
자세한 내용은 네이버 Maps API의 2019년 무료이용량 프로모션 종료 및 2020년 서비스 계획 안내 를 참고 하시기 바랍니다.

개요

Tile Map API는 다양한 지도 이미지 타일을 제공하는 REST API입니다. 일반 지도, 위성 지도, 지형도와 같은 지도 유형뿐 아니라 대중교통, 자전거 도로, 실시간 교통 정보 등의 세부 정보를 포함한 지도를 이미지 타일로 제공합니다. Tile Map API는 다음과 같은 특징을 제공합니다. - 이미지의 해상도를 지정할 수 있습니다. - SDK에서 제공하지 않는 다양한 조합의 지도를 요청할 수 있습니다. - 다양한 경로로 입수한 데이터와 쉽게 매시업할 수 있어 지도를 좀 더 전문적으로 응용할 수 있습니다. - OpenLayers, QGIS, ArcGIS, Mapbox 등 다양한 GIS 도구에서 통합 및 응용할 수 있습니다.

메르카토르 투영법(Mercator projection)

Tile Map API는 정규화된 메르카토르 투영법을 사용하여 원형인 지구 위 한 점을 평면에 있는 점으로 매핑해서 얻은 지도 타일을 제공합니다. Google Maps, Bing Maps와 같은 타일 시스템을 사용하며, 자세한 내용은 Mercator projection을 참고하세요. - 기본적으로 전 세계 영역을 표현할 수 있지만, 제공 정책에 따라 표현 가능한 영역이 제한될 수 있습니다. - 경위도 좌표와 타일 인덱스 간 변환이 필요하면 여러 언어로 작성된 변환 코드를 확인하세요.

요청

ID-KEY 기반 인증

curl "https://naveropenapi.apigw.ntruss.com/map-tile/v1/raster/styles/basic/{Z}/{X}/{Y}@{Scale}x.{Format}?mt={SubType}" \
	-H "X-NCP-APIGW-API-KEY-ID: {애플리케이션 등록 시 발급받은 client id값}" \
	-H "X-NCP-APIGW-API-KEY: {애플리케이션 등록 시 발급받은 client secret값}" -v

HTTP Referer 기반 인증

<img src="https://naveropenapi.apigw.ntruss.com/map-tile/v1/raster-cors/styles/basic/{Z}/{X}/{Y}@{Scale}x.{Format}?mt={SubType}&X-NCP-APIGW-API-KEY-ID={애플리케이션 등록 시 발급받은 client id값}">

요청 파라미터

URL 파라미터 타입 필수 여부 설명
MapType string Y 요청할 지도 유형. 입력 가능한 값은 다음과 같습니다.
- basic: 일반 지도
- satellite: 위성 지도
- terrain: 지형도
Z number Y 지도 이미지의 확대/축소 수준입니다.
최소 및 최대 zoom 레벨은 0~21입니다.
X number Y 요청할 타일의 가로 위치를 지정합니다.
지정 가능한 범위는 0부터 시작하고 최대 범위는 zoom 레벨에 따라 다릅니다.
최대 지정 가능한 X 범위 = 2 zoom
Y number Y 요청할 타일의 세로 위치를 지정합니다.
지정 가능한 범위는 0부터 시작하고 최대 범위는 zoom 레벨에 따라 다릅니다.
최대 지정 가능한 Y 범위 = 2 zoom
Scale number N 요청할 타일의 해상도. 생략하면 256 x 256 타일 반환.
입력 가능한 값은 다음과 같습니다.
- 1: 256 x 256 픽셀(기본값)
- 2: 512 x 512 픽셀
Format string N 응답 형식. 입력 가능한 값은 다음과 같습니다.
- jpg 또는 jpeg: 일반적으로 선택하는 응답 형식으로 적합합니다. SubType에 bg를 지정한 경우 jpg로 지정할 것을 권장합니다.
- png: 알파 채널을 지원하므로 SubType에 bg를 지정하지 않은 경우 배경이 투명인 이미지를 얻을 수 있습니다. 예를 들어, SubType으로 ctt만 요청하면 투명 배경의 실시간 교통정보 타일만 응답합니다.
- webp: 크롬, 오페라, 삼성 인터넷, Pale Moon 브라우저, 안드로이드 4.0 이상 순정 웹 브라우저 등 webp를 지원하는 환경에서 사용을 권장합니다. 타 형식에 비해 크기가 작고 응답이 빠르지만 지원하는 환경이 제한적입니다.
SubType string N 세부 지도 유형. 마침표(.)을 구분자로 원하는 세부 지도 유형을 조합할 수 있습니다. 이 값을 생략하면 기본값으로 bg.ol.ts.ar.lko 유형의 타일을 반환합니다.
- bg: 해당하는 지도 유형의 배경 표시
- ol: 실폭 도로, 실선 도로, 행정 경계, 공원 상세, 도로시설물, 시설, 역과 같이 세밀한 요소 표현
- ts: 지하철 노선도, 버스 정류장과 같이 대중교통 관련 요소 표현
- pr: 거리뷰, 항공뷰, 수중뷰와 같이 파노라마 촬영 위치 관련 요소 표현
- br: 자전거 관련 요소 표현
- ar: 등산로 관련 요소 표현
- ctt: 혼잡 교통정보 표현. 교통정보는 단시간(약 1~5분) 동안만 유효하다는 점에 유의해야 하며, 클라이언트 응용프로그램은 이 유형의 타일을 캐시해서는 안 됩니다.
- lko: 한국어 라벨 표현
- len: 영어 라벨 표현
- lzh: 중국어 라벨 표현
- lja: 일본어 라벨 표현

지도 유형

Tile Map API에서 지원하는 지도 유형은 다음과 같습니다.

  • 일반 지도(basic)

basic

  • 위성 지도(satellite)

satellite

  • 지형도(terrain)

terrain

요청 헤더

해당 헤더는 ID-KEY 기반 인증에서만 필요로 합니다.

헤더명 설명
X-NCP-APIGW-API-KEY-ID 앱 등록 시 발급받은 Client ID
X-NCP-APIGW-API-KEY-ID:{Client ID}
X-NCP-APIGW-API-KEY 앱 등록 시 발급 받은 Client Secret
X-NCP-APIGW-API-KEY:{Client Secret}

요청 바디

  • 해당 API 는 요청 바디를 필요로 하지 않습니다.

응답

응답 바디

정상적인 요청일 경우 파라미터에 맞게 한 장의 이미지 파일(png나 jpeg)을 반환합니다. 오류가 발생하면 HTTP 상태 코드 200이 아닌 값이 JSON 형식으로 반환됩니다.

예시

요청 예시

빠르게 시작하기

다음은 대한민국, 서울역의 이미지 타일 요청 예제입니다.

16 레벨에서 가로세로 256 x 256 픽셀인 일반 지도 배경에 세부 요소를 추가하고 지하철, 버스 정류장과 한국어 라벨을 포함한 타일을 요청합니다.

https://naveropenapi.apigw.ntruss.com/map-tile/v1/raster/styles/basic/16/55882/25381@1x.jpg?mt=bg.ol.ts.ar.lko

요청 결과는 다음과 같습니다.

서울역

지도 유형별 타일 요청

일반 지도 배경 요청

다음은 일반 지도 배경에 줌 레벨은 7 레벨, 가로 109, 세로 49 크기의 타일을 요청하는 예제입니다.

https://naveropenapi.apigw.ntruss.com/map-tile/v1/raster/styles/basic/7/109/49@1x.jpg?mt=bg

요청 결과는 다음과 같습니다.

basic_bg

일반 지도 배경에 세부 요소와 한국어 라벨 요청

다음은 일반 지도 배경에 세부 요소와 한국어 라벨을 표시한 타일을 요청하는 예제입니다.

https://naveropenapi.apigw.ntruss.com/map-tile/v1/raster/styles/basic/7/109/49@1x.jpg?mt=bg.ol.lko

요청 결과는 다음과 같습니다.

basic_bg.ol.lko

위성 지도 배경에 자전거 도로 요청

다음은 위성 지도 배경에 자전거 도로를 표시한 타일을 요청하는 예제입니다.

https://naveropenapi.apigw.ntruss.com/map-tile/v1/raster/styles/satellite/7/109/49@1x.jpg?mt=bg.br

요청 결과는 다음과 같습니다.

satellite_bg.br

실시간 혼잡 교통 정보 요청

다음은 투명 배경에 실시간 혼잡 교통 정보만를 표시한 타일을 요청하는 예제입니다.

https://naveropenapi.apigw.ntruss.com/map-tile/v1/raster/styles/basic/7/109/49@1x.png?mt=ctt

요청 결과는 다음과 같습니다.

basic_ctt

256 x 256 사이즈의 일반 지도 요청

다음은 해상도가 256 x 256인 일반 지도 타일을 요청하는 예제입니다.

https://naveropenapi.apigw.ntruss.com/map-tile/v1/raster/styles/basic/7/109/49@1x.jpg?mt=bg.ol.ts.lko

요청 결과는 다음과 같습니다.

256x256

512 x 512 사이즈의 지형도 요청

다음은 해상도가 512 x 512이고 세부 정보와 라벨이 제외된 지형도 타일을 요청하는 예제입니다.

https://naveropenapi.apigw.ntruss.com/map-tile/v1/raster/styles/terrain/7/109/49@2x.jpg?mt=bg

요청 결과는 다음과 같습니다.

512x512

오류 코드

HttpStatusCode ErrorCode ErrorMessage Description
400 100 Bad request 요청에 유효하지 않은 파라미터가 있음을 나타냅니다.
404 300 Not found 요청한 타일을 찾을 수 없음을 나타냅니다.(예: 지정된 Z/X/Y값이 서비스 범위를 넘은 경우)
503 500 Service Unavailable 시스템 유지보수로 인해 일시적인 응답 불가 상태입니다.
잠시 후 재시도하시기 바랍니다.
504 510 Gateway Timeout 시스템 과부하로 인해 일시적인 응답 불가 상태입니다.
잠시 후 재시도하시기 바랍니다.
500 900 Internal error 서버 내부에 오류가 발생했음을 의미합니다.
지속적으로 문제 발생 시 공식 문의 채널을 확인해 주세요.
아쉬운 점이 있다면 이야기해 주세요.
0/5000
내용을 입력해 주세요
의견 보내기