지오코더 API 개발자 설명서

목차

소개 인증 주소 지오코딩 역 지오코딩 토큰 통계 행정동 이력

소개

지오코더 API는 주소를 지리적 좌표로 변환하고, 좌표를 주소로 변환하는 기능을 제공합니다.

이 API를 통해 다음과 같은 기능을 사용할 수 있습니다:

인증

모든 API 요청은 토큰 기반 인증을 사용합니다. 토큰은 URL 파라미터로 제공합니다.

예: ?token=YOUR_API_TOKEN

주소 지오코딩

주소를 지리적 좌표(위도, 경도)로 변환합니다.

GET 지오코딩

GET /geocode

요청 파라미터

파라미터 타입 필수 설명
q string 예 하나 이상의 주소를 포함하는 문자열. 각 주소는 줄바꿈(\\n)으로 구분
token string 예 API 인증 토큰

요청 예제

GET /geocode?q=서울특별시%20송파구%20송파대로8길%2010%0A김제%20온천길%2037&token=YOUR_API_TOKEN

응답 예제

{
  "total_time": 0.15,
  "total_count": 2,
  "success_count": 2,
  "fail_count": 0,
  "results": [
    {
      "x": 966445,
      "y": 1949518,
      "z": "05512",
      "hc": "1174064000",
      "lc": "1174010900",
      "rc": "117406103008",
      "bn": "10",
      "h1": "서울특별시",
      "rm": "송파대로8길",
      "bm": ["풍림아이원아파트"],
      "hd_cd": "1174064000",
      "hd_nm": "방이2동",
      "success": true,
      "errmsg": "",
      "h1_cd": "11",
      "h2_cd": "11740",
      "kostat_h1_cd": "11",
      "kostat_h2_cd": "11740",
      "hash": "e93a83cf",
      "address": "서울특별시 송파구 송파대로8길 10",
      "addressCls": "ROAD",
      "toksString": "서울특별시|송파구|송파대로8길|10",
      "x_axis": 127.1146829,
      "y_axis": 37.5138498,
      "inputaddr": "서울특별시 송파구 송파대로8길 10"
    },
    {
      "x": 933939,
      "y": 1769049,
      "z": "54332",
      "hc": "4521054000",
      "lc": "4521054000",
      "rc": "452105304150",
      "bn": "37",
      "h1": "전라북도",
      "rm": "온천길",
      "bm": [],
      "hd_cd": "4521054000",
      "hd_nm": "교월동",
      "success": true,
      "errmsg": "",
      "h1_cd": "45",
      "h2_cd": "45210",
      "kostat_h1_cd": "45",
      "kostat_h2_cd": "45210",
      "hash": "4e7a9e2a",
      "address": "전라북도 김제시 온천길 37",
      "addressCls": "ROAD",
      "toksString": "전라북도|김제시|온천길|37",
      "x_axis": 126.8632492,
      "y_axis": 35.8298487,
      "inputaddr": "김제 온천길 37"
    }
  ]
}

POST 지오코딩

POST /geocode

요청 파라미터

파라미터 타입 필수 설명
data object 예 지오코딩할 주소 목록
token string 예 API 인증 토큰

요청 본문 예제

{
  "q": [
    "서울특별시 송파구 송파대로8길 10",
    "김제 온천길 37",
    "강원 춘천시 남산면 서천리 산111"
  ]
}

응답 형식

GET 지오코딩과 동일한 응답 형식입니다.

응답 필드 설명

필드 타입 설명
total_time float 총 처리 시간 (초)
total_count integer 총 요청 주소 개수
success_count integer 성공한 주소 개수
fail_count integer 실패한 주소 개수
results array 지오코딩 결과 목록

결과 객체 필드

필드 타입 설명
x integer 원본 X 좌표 (EPSG:5179)
y integer 원본 Y 좌표 (EPSG:5179)
z string 우편번호
hc string 행정동 코드
lc string 법정동 코드
rc string 도로명 코드
bn string 건물 번호
h1 string 행정구역 1 (시도명)
rm string 도로명
bm array 건물명 목록
hd_cd string 행정동 코드
hd_nm string 행정동 이름
success boolean 지오코딩 성공 여부
errmsg string 오류 메시지
h1_cd string 행정구역 1 코드
h2_cd string 행정구역 2 코드
kostat_h1_cd string 통계청 행정구역 1 코드
kostat_h2_cd string 통계청 행정구역 2 코드
hash string 해시 값
address string 전체 주소
addressCls string 주소 분류
toksString string 토큰화된 문자열
x_axis float 경도 (EPSG:4326)
y_axis float 위도 (EPSG:4326)
inputaddr string 입력 주소

역 지오코딩

지리적 좌표(위도, 경도)를 주소로 변환합니다.

GET /reverse_geocode

요청 파라미터

파라미터 타입 필수 설명
x float 예 경도 좌표 (EPSG:4326)
y float 예 위도 좌표 (EPSG:4326)
token string 예 API 인증 토큰

요청 예제

GET /reverse_geocode?x=127.1146829&y=37.5138498&token=YOUR_API_TOKEN

응답 예제

{
  "ADR_MNG_NO": "1174010900110040000",
  "yyyymm": "202306",
  "address": "서울특별시 송파구 송파대로8길 10",
  "success": true,
  "geom": "POINT(127.1146829 37.5138498)",
  "errmsg": ""
}

응답 필드 설명

필드 타입 설명
ADR_MNG_NO string 주소 관리 번호
yyyymm string 데이터 기준 년월 (YYYYMM 형식, 예: 202306)
address string 전체 주소 (도로명 또는 지번)
success boolean 리버스 지오코딩 성공 여부
geom string WKT 형식의 지오메트리 정보 (예: POINT(X Y))
errmsg string 오류 발생 시 오류 메시지

토큰 통계

API 토큰의 사용량 통계를 조회합니다.

GET /token/stats

요청 파라미터

파라미터 타입 필수 설명
token string 예 통계를 조회할 API 토큰

요청 예제

GET /token/stats?token=YOUR_API_TOKEN

응답 예제

{
  "token_id": "123e4567-e89b-12d3-a456-426614174000",
  "user_id": "user@example.com",
  "created_date": "2023-01-01T00:00:00",
  "expiry_date": "2024-01-01T00:00:00",
  "is_active": true,
  "token_type": "premium",
  "usage_count": 15204,
  "quarter": 100000,
  "remaining": 84796,
  "percentage": 15.204
}

응답 필드 설명

필드 타입 설명
token_id string 토큰 고유 식별자
user_id string 토큰 소유 사용자 ID
created_date string 토큰 생성 일시
expiry_date string 토큰 만료 일시
is_active boolean 토큰 활성화 상태
token_type string 토큰 유형
usage_count integer 현재까지 사용된 요청 수
quarter integer 할당된 분기별 요청 수
remaining integer 남은 요청 수
percentage float 사용 비율 (%)

행정동 이력

행정동 이력 정보를 조회합니다.

GET /hd_history

요청 파라미터

파라미터 타입 필수 설명
hd_cd string 예 행정동 코드 (8자리)
token string 예 API 인증 토큰

요청 예제

GET /hd_history?hd_cd=1174064000&token=YOUR_API_TOKEN

응답 예제

[
  {
    "EMD_CD": "1174064000",
    "EMD_KOR_NM": "방이2동",
    "EMD_ENG_NM": "Bangi 2-dong",
    "from_yyyymm": "201001",
    "to_yyyymm": "202306"
  },
  {
    "EMD_CD": "1174063000",
    "EMD_KOR_NM": "방이동",
    "EMD_ENG_NM": "Bangi-dong",
    "from_yyyymm": "199501",
    "to_yyyymm": "200912"
  }
]

응답 필드 설명

필드 타입 설명
EMD_CD string 행정동 코드 (8자리)
EMD_KOR_NM string 행정동 한글 이름 (예: 방이2동)
EMD_ENG_NM string 행정동 영어 이름 (예: Bangi 2-dong)
from_yyyymm string 시작 년월 (YYYYMM 형식, 예: 201001)
to_yyyymm string 종료 년월 (YYYYMM 형식, 예: 202306)