Koharu Maps REST API Reference

Official Documentation & Specification for https://map.koharu.live · 개발: KCS - Koharu Coding Server

무료 API 키 발급지도로 돌아가기

인증 및 엔드포인트 기본 규격

모든 API 요청은 표준 HTTPS 프로토콜을 사용하며, 응답 데이터는 JSON 형식(UTF-8)으로 반환됩니다. 인증 헤더는 선택 사항이며, 발급받은 무료 API 키를 헤더에 포함할 경우 사용량 통계가 집계됩니다.

기본 URL: https://map.koharu.live/api/v1 · 헤더: X-API-Key: YOUR_API_KEY
GET/api/v1/search

전 세계 대도시 및 대한민국 행정구역, 랜드마크, 도로명 주소를 역색인(Inverted Index) 기반으로 초고속 검색합니다.

파라미터타입필수설명
qstring필수검색 키워드 (예: "강남역", "뉴욕", "도쿄", "세종대로")
limitnumber선택최대 반환 개수 (기본값: 10, 최대: 50)
center_lon / center_latnumber선택현재 뷰포트 중심 좌표 (거리 근접도 가중치 부여)
{
  "status": "success",
  "query": "강남역",
  "count": 1,
  "results": [
    {
      "id": "p_6",
      "name": "강남역",
      "category": "교통/상업",
      "address": "서울특별시 강남구 강남대로 396",
      "location": { "lon": 127.0280, "lat": 37.4980 },
      "score": 100
    }
  ]
}
GET/api/v1/reverse-geocode

지정된 WGS84 위도와 경도에서 가장 가까운 도로명 주소, 랜드마크 명칭 및 거리를 반환합니다.

파라미터타입필수설명
lonnumber필수경도 (Longitude, WGS84)
latnumber필수위도 (Latitude, WGS84)
GET/api/v1/route

출발지와 도착지 좌표를 도로망에 스냅하여 A* 알고리즘으로 최적 경로, 총 거리, 예상 소요 시간 및 턴바이턴 주행 안내를 생성합니다.

// 요청 예시
GET https://map.koharu.live/api/v1/route?start=126.9768,37.5750&target=127.0280,37.4980

// 응답 예시
{
  "status": "success",
  "algorithm": "a_star",
  "route": {
    "distanceM": 10540,
    "durationSec": 780,
    "durationMin": 13,
    "coordinates": [[126.9768, 37.575], [126.977, 37.566]],
    "instructions": [
      { "type": "depart", "message": "세종대로 방면으로 출발합니다.", "distanceM": 1000 },
      { "type": "turn-right", "message": "강남대로 방면으로 우회전입니다.", "distanceM": 1500 },
      { "type": "arrive", "message": "목적지에 도착했습니다." }
    ]
  }
}