iNavi Maps 통합 검색 API Reference

Restful API 기반 통합 검색 API 를 사용하는 방법을 설명 합니다.

iNavi Maps API 를 사용하기 위해서는 Appkey 발급이 필요합니다.
Toast 사이트에서 ‘Maps’ 상품을 신청하여 AppKey 발급을 받으면 iNavi Maps API 를 사용 하실 수 있습니다.

자세한 사항은 Toast Maps 상품안내 를 참고해주세요.

통합 검색 직접 해보기

상호명, 전화번호, 주소 등의 키워드에 대해 통합 정보를 검색합니다.

  • Request URL

    Http Method URL
    GET https://api-maps.cloud.toast.com/maps/v3.0/appkeys/{appkey}/searches
  • Request Path Parameter

    타입 설명
    appKey String 고유의 appKey
  • Request Query Parameters

    타입 필수 설명
    query String O 검색어
    coordtype String X 좌표형식
    • Default : 1
    • 0 : TW
    • 1 : WGS84
    • 2 : TM
    startposition String X 검색 시작 위치 0 : 첫번째 위치 * 미입력 시 0으로 조회
    reqcount String X 검색 요청 개수
    • reqcount : type별 개수
    • type : POI(명칭), TEL(전화번호), ADM(주소)
    • ex) reqcount=10 이면, type별로 count 가 반환되어 합산
    • * 0으로 설정시 Max Count(100) 반환
    spopt String X 공간검색 option
    • 0 : 공간검색 사용 안함
    • 1 : Extent(공간) 검색
    • 2 : Range(반경) 검색
    • * spopt값이 설정되지 않은 경우 0으로 설정
    radius String X 반경 spopt가 2인 경우 사용 (meter 단위)
    admcode String X 법정동/행정동 코드
    • 키워드가 법정동 검색일 때, 결과값은 법정동 코드
    • 키워드가 행정동 검색일 때, 결과값은 행정동 코드
    depth String X 하위시설물 요구 depth
    • 1 : 1 depth 만 요청 (최상위 depth)
    • 2 : 2 depth 까지 요청
    • 3 : 3 depth 까지 요청
    • * depth값이 설정되지 않은 경우 1로 설정
    x1 String X X1좌표
    • spopt가 0인 경우 기준점 X좌표
    • spopt가 1인 경우 Extent의 좌상단 X좌표
    • spopt가 2인 경우 기준점 X좌표
    y1 String X Y1좌표
    • spopt가 0인 경우 기준점 Y좌표
    • spopt가 1인 경우 Extent의 좌상단 Y좌표
    • spopt가 2인 경우 기준점 Y좌표
    x2 String X X2좌표
    • spopt가 1인 경우 Extent의 우하단 X좌표
    • spopt가 2인 경우 사용 안함
    y2 String X Y2좌표
    • spopt가 1인 경우 Extent의 우하단 Y좌표
    • spopt가 2인 경우 사용 안함
    sortopt String X 정렬option
    • 1 : 명칭순 정렬
    • 2 : 거리순 정렬 (좌표를 입력한 경우)
    • 3 : 이름매치 → 거리순 정렬 (좌표를 입력한 경우)
    • 4 : 검색어 Weight(가중치) 정렬
    * sortopt 값이 설정되지 않은 경우 4로 설정
  • Response Field

    타입 설명
    header (Object) isSuccessful Boolean 성공 여부
    resultCode Integer 실패 코드
    resultMessage String 실패 메시지
    search (Object) type Integer
    1. 0 : 일반 검색
    2. 1 : 연관 검색
    ex) 연관 검색 : 판교역 주변 주유소
    totalcount Integer 전체 검색결과 대상 개수 (POI + TEL_POI + ADM) poitotalcount + tel_poitotalcount + admtotalcount
    count Integer 검색 결과 개수 (POI + TEL_POI) poicount + tel_poicount
    poitotalcount Integer 전체 POI(명칭) 검색결과 대상 개수
    poicount Integer POI(명칭) 검색 결과 개수
    tel_poitotalcount Integer 전체 TEL_POI 검색결과 대상 개수
    tel_poicount Integer TEL_POI 검색 결과 개수
    admtotalcount Integer 전체 ADM(주소) 검색 결과 대상 개수
    admcount Integer ADM(주소) 검색 결과 개수
    reftotalcount Integer 전체 연관 검색 결과 대상 개수
    refcount Integer 연관 검색 결과 개수
    res_type String 검색 결과 Type명칭 POI(명칭), CATEGORY(카테고리), ADM(주소), TEL_POI(전화번호 POI) 순 ex) NYNN: 명칭 No, 카테고리 YES, 주소 NO, 전화번호 NO
    poi (Array) poiid Integer POI ID
    depth String POI 하위시설물 depth
    dpx String display X좌표(WGS84의 경우 longitude)
    dpy String display Y좌표(WGS84의 경우 latitude)
    rpx String 탐색 X좌표(WGS84의 경우 longitude) 경로 탐색에 사용되는 X좌표
    rpy String 탐색 Y좌표(WGS84의 경우 latitude) 경로 탐색에 사용되는 Y좌표
    name1 String 정식명칭
    name2 String 축약명칭
    name3 String 확장명칭1
    name4 String 확장명칭2
    admcode String 법정동/행정동 코드
    • 키워드가 법정동 검색일 때, 결과값은 법정동 코드
    • 키워드가 행정동 검색일 때, 결과값은 행정동 코드
    address String 주소
    jibun String 지번
    roadname String 새주소 도로명
    roadjibun String 새주소 지번
    detailaddress String 상세주소
    catecode String 분류코드
    catename String 분류명칭
    distance Integer 좌표와의 거리 (meter 단위) x1, y1 좌표를 기준으로 계산한 거리를 반환
    tel String 전화번호
    hasdetailinfo Boolean 상세 정보 존재여부 true : POI 상세 검색 API 에서 POI 상세 정보 확인 가능
    tel Array TEL 검색 결과 목록 POI (Array) 정보와 동일
    adm (Array) ADM 검색 결과 목록 posx String X좌표 (WGS84의 경우 longitude)
    posy String Y좌표 (WGS84의 경우 latitude)
    admcode String 법정동/행정동 코드
    • 키워드가 법정동 검색일 때, 결과값은 법정동 코드
    • 키워드가 행정동 검색일 때, 결과값은 행정동 코드
    address String 주소
    jibun String 지번
    roadname String 새주소 도로명
    roadjibun String 새주소 지번

POI 상세 검색 직접 해보기

POI에 대한 상세 정보를 검색합니다.

  • Request URL

    Http Method URL
    GET https://api-maps.cloud.toast.com/maps/v3.0/appkeys/{appkey}/pois
  • Request Path Parameter

    타입 설명
    appKey String 고유의 appKey
  • Request Query Parameters

    타입 필수 설명
    poiid String O POI ID poiid를 구분자","와 함께 입력 (복수개 가능 186개까지) ex) poiid=717788,8972661,7630525
  • Response Field

    타입 설명
    header (Object) isSuccessful Boolean 성공 여부
    resultCode Integer 실패 코드
    resultMessage String 실패 메시지
    poi (Object) totalcount Integer 전체 검색결과 대상 개수
    count Integer 검색 결과 개수
    poiinfo (Array) poiid Integer POI ID
    dpx String display X좌표 (WGS84의 경우 longitude)
    dpy String display Y좌표 (WGS84의 경우 latitude)
    rpx String 탐색 X좌표 (WGS84의 경우 longitude) 경로 탐색에 사용되는 X좌표
    rpy String 탐색 Y좌표 (WGS84의 경우 latitude) 경로 탐색에 사용되는 Y좌표
    name1 String 정식명칭
    name2 String 축약명칭
    name3 String 확장명칭1
    name4 String 확장명칭2
    admcode String 법정동 코드
    address String 주소
    jibun String 지번
    roadname String 새주소 도로명
    roadjibun String 새주소 지번
    detailaddress String 상세주소
    catecode String 분류코드
    catename String 분류명칭
    fulladdress String 전체주소 (행정주소+지번+상세주소)
    zip String 우편번호
    homeage String 홈페이지 url
    email String email
    howtogo String 교통편
    tel1 String 전화번호1
    tel2 String 전화번호2
    fax1 String 팩스번호1
    fax2 String 팩스번호2
    detail_count Integer 분류 상세 항목 갯수
    etc_count Integer 분류 기타 항목 갯수
    detailinfo (Array) name String 분류 상세 항목 설명
    value String 분류 상세 항목 내용
    etcinfo (Array) name String 분류 기타 항목 설명
    value String 분류 기타 항목 내용

POI 하위 시설물 검색 직접 해보기

특정 POI에 대한 하위 시설물을 검색합니다.

  • Request URL

    Http Method URL
    GET https://api-maps.cloud.toast.com/maps/v3.0/appkeys/{appkey}/sub-pois
  • Request Path Parameter

    타입 설명
    appKey String 고유의 appKey
  • Request Query Parameters

    타입 필수 설명
    poiid String O POI ID 복수개 지원 안됨
    x1 String X 현위치 또는 지도 중심 좌표 x, y좌표가 모두 NULL 또는 0일 경우 거리 계산을 수행하지 않음 복수개 지원 안됨
    y1 String X 현위치 또는 지도 중심 좌표 x, y좌표가 모두 NULL 또는 0일 경우 거리 계산을 수행하지 않음 복수개 지원 안됨
  • Response Field

    타입 설명
    header (Object) isSuccessful Boolean 성공 여부
    resultCode Integer 실패 코드
    resultMessage String 실패 메시지
    subpoi (Object) totalcount Integer 전체 검색결과 대상 개수
    count Integer 검색 결과 개수
    poi (Array) poiid Integer POI ID
    depth String POI 하위시설물 depth
    dpx String display X좌표 (WGS84의 경우 longitude)
    dpy String display Y좌표 (WGS84의 경우 latitude)
    rpx String 탐색 X좌표 (WGS84의 경우 longitude) 경로 탐색에 사용되는 X좌표
    rpy String 탐색 Y좌표 (WGS84의 경우 latitude) 경로 탐색에 사용되는 Y좌표
    name1 String 정식명칭
    name2 String 축약명칭
    name3 String 확장명칭1
    name4 String 확장명칭2
    admcode String 법정동 코드
    address String 주소
    jibun String 지번
    roadname String 새주소 도로명
    roadjibun String 새주소 지번
    detailaddress String 상세주소
    catecode String 분류코드
    catename String 분류명칭
    distance Integer 좌표와의 거리 (meter 단위) x1, y1 좌표를 기준으로 계산한 거리를 반환
    tel String 전화번호

추천어 검색 직접 해보기

검색어의 추천어를 검색합니다.

  • Request URL

    Http Method URL
    GET https://api-maps.cloud.toast.com/maps/v3.0/appkeys/{appkey}/proposers
  • Request Path Parameter

    타입 설명
    appKey String 고유의 appKey
  • Request Query Parameters

    타입 필수 설명
    query String O 한글/영문/숫자 50Byte(한글 25자)
  • Response Field

    타입 설명
    header (Object) isSuccessful Boolean 성공 여부
    resultCode Integer 실패 코드
    resultMessage String 실패 메시지
    proposer (Object) count Integer 추천 검색어 개수
    keyword (Array) 추천 검색어 목록 keyword String 추천 검색어
    frequency Integer 조회 빈도

주변 카테고리 검색 직접 해보기

기준 좌표를 기준으로 주변 카테고리 검색기능을 지원합니다.

  • Request URL

    Http Method URL
    GET https://api-maps.cloud.toast.com/maps/v3.0/appkeys/{appkey}/nearby-category-searches
  • Request Path Parameter

    타입 설명
    appKey String 고유의 appKey
  • Request Query Parameters

    타입 필수 설명
    depth Integer O
    1. 0 : 전체 depth
    2. 1 : depth1
    3. 2 : depth2
    4. 3 : depth3
    spopt Integer O
    1. 1 : Extent (x1, y1, x2, y2)
    2. 2 : 반경검색 (x1, y1, radius)
    catecode String O 카테고리 코드
    x1 String O (spopt 참조) 기준 X1좌표
    y1 String O (spopt 참조) 기준 Y1좌표
    x2 String O (spopt 참조) 기준 X2좌표
    y2 String O (spopt 참조) 기준 Y2 좌표
    radius String O (spopt 참조) 반경(m)
  • Response Field

    타입 설명
    header (Object) isSuccessful Boolean 성공 여부
    resultCode Integer 실패 코드
    resultMessage String 실패 메시지
    cate (Object) result Boolean 성공 여부
    totalcount Integer 전체 검색 결과 대상 개수
    count Integer 검색 결과 개수
    poi (Array) POI 검색 결과 목록 poiid Integer POI ID
    dpx String display X좌표 (WGS84의 경우 longitude)
    dpy String display Y좌표 (WGS84의 경우 latitude)
    rpx String 탐색 X좌표 (WGS84의 경우 longitude) 경로 탐색에 사용되는 X좌표
    rpy String 탐색 Y좌표 (WGS84의 경우 latitude) 경로 탐색에 사용되는 Y좌표
    name1 String 정식명칭
    name2 String 축약명칭
    name3 String 확장명칭1
    name4 String 확장명칭2
    admcode String 법정동 코드
    address String 주소
    jibun String 지번
    roadname String 새주소 도로명
    roadjibun String 새주소 지번
    detailaddress String 상세주소
    catecode String 분류코드
    catename String 분류명칭
    fulladdress String 전체주소 (행정주소+지번+상세주소)
    zip String 우편번호
    homeage String 홈페이지 url
    email String email
    howtogo String 교통편
    tel1 String 전화번호1
    tel2 String 전화번호2
    fax1 String 팩스번호1
    fax2 String 팩스번호2
    detail_count Integer 분류 상세 항목 갯수
    etc_count Integer 분류 기타 항목 갯수
    detailinfo (Array) name String 분류 상세 항목 설명
    value String 분류 상세 항목 내용
    etcinfo (Array) name String 분류 기타 항목 설명
    value String 분류 기타 항목 내용
    hassubpoi Boolean 하위 시설물 데이터 존재 유무
    subpoi (Object) 하위 시설물 정보 count Integer 하위 시설물 개수
    poi Array POI 정보와 동일

Geocoding(주소 → 좌표) 직접 해보기

주소로 좌표(TW 좌표/WGS84 좌표/TM 좌표)를 검색합니다.

  • Request URL

    Http Method URL
    GET https://api-maps.cloud.toast.com/maps/v3.0/appkeys/{appkey}/coordinates
  • Request Path Parameter

    타입 설명
    appKey String 고유의 appKey
  • Request Query Parameters

    타입 필수 설명
    query String O 검색어
    coordtype String X 좌표형식
    • Default : 1
    • 0 : TW
    • 1 : WGS84
    • 2 : TM
    startposition String X 검색 시작 위치 0 : 첫번째 위치 * 미입력 시 0으로 조회
    reqcount String X 검색 요청 개수 * 0으로 설정시 Max Count(100) 반환
    admcode String X 법정동/행정동 코드
    • 키워드가 법정동 검색일 때, 결과값은 법정동 코드
    • 키워드가 행정동 검색일 때, 결과값은 행정동 코드
  • Response Field

    타입 설명
    header (Object) isSuccessful Boolean 성공 여부
    resultCode Integer 실패 코드
    resultMessage String 실패 메시지
    address (Object) totalcount Integer 전체 검색결과 대상 개수
    res_type String 검색 결과 Type명칭 POI(명칭), CATEGORY(카테고리), ADM(주소), TEL_POI(전화번호 POI) 순 ex) NYNN: 명칭 No, 카테고리 YES, 주소 NO, 전화번호 NO
    adm (Array) 검색결과 posx String X좌표
    posy String Y좌표
    admcode String 법정동/행정동 코드
    • 키워드가 법정동 검색일 때, 결과값은 법정동 코드
    • 키워드가 행정동 검색일 때, 결과값은 행정동 코드
    address String 주소
    roadname String 새주소 도로명
    roadjibun String 새주소 지번

Reverse Geocoding(좌표 → 주소) 직접 해보기

좌표(TW 좌표/WGS84 좌표)로 주소를 검색합니다.

  • Request URL

    Http Method URL
    GET https://api-maps.cloud.toast.com/maps/v3.0/appkeys/{appkey}/addresses
  • Request Path Parameter

    타입 설명
    appKey String 고유의 appKey
  • Request Query Parameters

    타입 필수 설명
    posX String O X좌표
    posY String O Y좌표
    coordtype String X 좌표형식
    • Default : 1
    • 0 : TW
    • 1 : WGS84
  • Response Field

    타입 설명
    header (Object) isSuccessful Boolean 성공 여부
    resultCode Integer 실패 코드
    resultMessage String 실패 메시지
    location (Object) hasAdmAddress Boolean 행정동 주소 반환 여부
    adm (Object) 기본(법정동) 주소 정보 posx String X좌표
    posy String Y좌표
    address String 주소
    distance Integer 좌표와의 거리 (meter 단위) x1, y1 좌표를 기준으로 계산한 거리를 반환
    admcode String 법정동 코드
    jibun String 지번
    roadname String 새주소 도로명
    roadjibun String 새주소 지번
    bldname String 건물명
    postcode String 우편번호
    adm_address (Object) 행정동 주소 정보 address String 주소
    admcode String 행정동 코드
    address_category1 String 도/시
    address_category2 String 시/군/구
    address_category3 String 읍/면/동
    address_category4 String
    jibun String 지번
    cut_address String 축약주소
    legal_address (Object) 법정동 주소 정보 address String 주소
    admcode String 법정동 코드
    address_category1 String 도/시
    address_category2 String 시/군/구
    address_category3 String 읍/면/동
    address_category4 String
    jibun String 지번
    cut_address String 축약주소

좌표변환 (WGS84 ⟷ TM) 직접 해보기

WGS84 ⟷ TM 좌표간 변환값을 반환합니다.

  • Request URL

    Http Method URL
    GET https://api-maps.cloud.toast.com/maps/v3.0/appkeys/{appkey}/trans-coordinates
  • Request Path Parameter

    타입 설명
    appKey String 고유의 appKey
  • Request Query Parameters

    타입 필수 설명
    coordtype String O 좌표형식
    • 0 : WGS84 → TM
    • 1 : TM → WGS84
    x String O X좌표
    y String O Y좌표
  • Response Field

    타입 설명
    header (Object) isSuccessful Boolean 성공 여부
    resultCode Integer 실패 코드
    resultMessage String 실패 메시지
    coordinate (Object) coordtype String 변환 좌표 형태
    x String 변환 X좌표
    y String 변환 Y좌표

결과코드

결과 코드값 리스트

  • 결과코드

    resultCode resultMessage 비고 설명
    0 공통 성공
    100 Result Not Found 검색전용 결과없음
    101 Argument Error 공통 파라미터 오류
    102 Internal Server Error 검색전용 서버 오류
    201 Searching for Security 검색전용 POI 보안시설물
    202 Longitude/Latitude 검색전용 경위도
    203 Mobile Phone Number 검색전용 전화번호(Mobile)
    204 Invalid Query 검색전용 서버 오류
    205 POI not in given Admin 검색전용 결과없음(지역설정)
    206 POI not in given Area 검색전용 결과없음(영역설정)
    207 POI not in given Category 검색전용 결과없음(분류설정)
    208 Neighbor Search Only 검색전용 결과없음(주변검색만입력)
    209 Neighbor Search not Found 검색전용 결과없음(주변 + 키워드 검색 결과 없음)
    300 AppKey Error 공통 AppKey 인증 오류

×
Request Parameters
Response
Result