지오코더 설명서

소개

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

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

• 주소 지오코딩 - 주소를 위도/경도 좌표로 변환
• 역 지오코딩 - 위도/경도 좌표를 주소로 변환
• 영역 검색 - 주어진 코드로 행정구역 영역(광역시도, 시군구, 행정동)을 찾아 형상을 추출합니다
• 주어진 좌표에 대한 행정동을 조회합니다.
• 토큰 사용량 통계 확인
• 행정동 이력 조회

인증

모든 API 요청은 토큰 기반 인증을 사용합니다. 회원 가입시 토큰이 발급됩니다. 내 프로필에서 발급된 토큰을 확인하세요.

토큰은 비밀번호와 같이 안전하게 보관하세요. 토큰에 일일 사용량과 월간 사용량이 할당됩니다.

토큰을 API 요청 시 전달해야 합니다. 인증되지 않은 요청은 거부됩니다.

예: ?token=YOUR_API_TOKEN

외부에 URL이 노출되는 서비스에서 API를 호출할 때는 token parameter 대신 HTTP 헤더에 Authorization: YOUR_API_TOKEN 형식으로 전달할 수 있습니다.

주소 지오코딩

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

GET 지오코딩

요청 파라미터

curl 요청 예제

curl 'https://geocode-api.gimi9.com/geocode?q=서울특별시 송파구 송파대로8길 10%0A김제 온천길 37&token=YOUR_API_TOKEN'

curl 'https://geocode-api.gimi9.com/geocode?q=%EC%84%9C%EC%9A%B8%ED%8A%B9%EB%B3%84%EC%8B%9C%20%EC%86%A1%ED%8C%8C%EA%B5%AC%20%EC%86%A1%ED%8C%8C%EB%8C%80%EB%A1%9C8%EA%B8%B8%2010%0A%EA%B9%80%EC%A0%9C%20%EC%98%A8%EC%B2%9C%EA%B8%B8%2037&token=YOUR_API_TOKEN'

python 요청 예제

import requests

params = {
    "q": "서울특별시 송파구 송파대로8길 10\n김제 온천길 37", # 줄 바꿈으로 주소를 구분하세요.
    "token": "YOUR_TOKEN",  # 여기에 실제 토큰을 입력하세요
}
url = "https://geocode-api.gimi9.com/geocode"
response = requests.get(url, params=params)
print(response.json())
            

응답 예제

{
  "document_id": null,
  "document_name": null,
  "total_time": 0.0036127567291259766,
  "total_count": 2,
  "success_count": 2,
  "hd_success_count": 2,
  "fail_count": 0,
  "results": [
    {
      "inputaddr": "서울특별시 송파구 송파대로8길 10",
      "success": true,
      "errmsg": "",
      "addressCls": "ROAD_ADDRESS",
      "x_axis": 127.1291683066244,
      "y_axis": 37.47688998121118,
      "z": "05813",
      "h1_nm": "서울",
      "h23_nm": "송파구",
      "hd_nm": "장지동",
      "rm": "송파대로8길",
      "h1_cd": "11",
      "h23_cd": "11710",
      "hd_cd": "1171064600",
      "hd_history": [
        {
          "hd_cd": "1171064600",
          "hd_nm": "장지동",
          "hd_en": "Jangji-dong",
          "from_yyyymm": "202305",
          "to_yyyymm": "202507"
        }
      ],
      "kostat_h1_cd": "11",
      "kostat_h2_cd": "11240",
      "bld_mgt_no": "1171010900102520004000001",
      "bm": [
        "송파파인13",
        "1304동"
      ]
    },
    {
      "inputaddr": "김제 온천길 37",
      "success": true,
      "errmsg": "인근 도로명 주소: 37-1",
      "addressCls": "ROAD_ADDRESS",
      "x_axis": 127.84423028792409,
      "y_axis": 37.70551640104829,
      "z": "25112",
      "h1_nm": "강원",
      "h23_nm": "홍천군",
      "hd_nm": "북방면",
      "rm": "온천길",
      "h1_cd": "51",
      "h23_cd": "51720",
      "hd_cd": "5172038000",
      "hd_history": [
        {
          "hd_cd": "5172038000",
          "hd_nm": "북방면",
          "hd_en": "Bukbang-myeon",
          "from_yyyymm": "202306",
          "to_yyyymm": "202507"
        },
        {
          "hd_cd": "4272038000",
          "hd_nm": "북방면",
          "hd_en": "Bukbang-myeon",
          "from_yyyymm": "202305",
          "to_yyyymm": "202305"
        }
      ],
      "kostat_h1_cd": "32",
      "kostat_h2_cd": "32510",
      "bld_mgt_no": "",
      "bm": []
    }
  ]
}

POST 지오코딩

대량의 주소를 한 번에 지오코딩할 수 있는 POST 방식의 API입니다.

GET 방식과 동일한 기능을 제공하지만, 요청 본문에 JSON 형식으로 주소 목록을 전달합니다. GET 방식에 비해 더 많은 주소를 한 번에 처리할 수 있습니다.

요청 파라미터

요청 본문 예제

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

curl 요청 예제

curl 'https://geocode-api.gimi9.com/geocode' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_TOKEN' \
  --data-raw $'{  "q": [    "서울특별시 송파구 송파대로8길 10",    "김제 온천길 37",    "강원 춘천시 남산면 서천리 산111"  ]}'
        

python 요청 예제

import requests
import json

url = "https://geocode-api.gimi9.com/geocode"
headers = {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_TOKEN"  # 여기에 실제 토큰을 입력하세요
}
data = {
    "q": [
    "서울특별시 송파구 송파대로8길 10",
    "김제 온천길 37",
    "강원 춘천시 남산면 서천리 산111"
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
            

응답 형식

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

응답 필드 설명

results array의 객체 필드

역 지오코딩

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

도로명 주소와 지번 주소를 모두 반환합니다. 도로명 주소가 없는 경우 지번 주소만 반환됩니다.

요청 파라미터

요청 예제

GET https://geocode-api.gimi9.com/reverse_geocode?x=127.1146829&y=37.5138498&token=YOUR_API_TOKEN

curl 요청 예제

curl 'https://geocode-api.gimi9.com/reverse_geocode?x=127.1146829&y=37.5138498&token=YOUR_API_TOKEN'

python 요청 예제

import requests

params = {
    "x": 127.1146829,
    "y": 37.5138498,
    "token": "YOUR_API_TOKEN"  # 여기에 실제 토큰을 입력하세요
}
url = "https://geocode-api.gimi9.com/reverse_geocode"
response = requests.get(url, params=params)
print(response.json())
        

응답 예제

{
  "road_addr": {
    "ADR_MNG_NO": "11710109416935500001000000",
    "yyyymm": "MST.46000",
    "address": "서울특별시 송파구 송파대로8길 10",
    "success": true,
    "geom": "POLYGON ((127.127840 37.477157, 생략...))",
    "errmsg": ""
  },
  "jibun_addr": {
    "PNU": "1171010900108570000",
    "yyyymm": "202404",
    "address": "서울특별시 송파구 장지동 857번지",
    "success": true,
    "geom": "POLYGON ((127.127839 37.477158, 생략...))",
    "errmsg": ""
  },
  "success": true
}

응답 필드 설명

road_addr / jibun_addr 객체 필드

코드로 행정구역 형상 검색

주어진 코드로 행정구역 영역(광역시도, 시군구, 행정동)을 찾아 지리적 형상 정보를 반환합니다.

특정 년월의 행정구역 정보를 조회할 수 있으며, 행정구역 경계의 WKT(Well-Known Text) 형식의 지오메트리 정보를 제공합니다.

요청 파라미터

요청 예제

GET https://geocode-api.gimi9.com/region?type=hd&code=1114055000&yyyymm=202506&token=YOUR_API_TOKEN

curl 요청 예제

curl 'https://geocode-api.gimi9.com/region?type=hd&code=1114055000&yyyymm=202506&token=YOUR_API_TOKEN'

python 요청 예제

import requests

params = {
    "type": "hd",           # 행정동
    "code": "1114055000,4111760000'",  # 명동, 수원 광교1동
    "yyyymm": "202506",    # 2025년 6월
    "token": "YOUR_API_TOKEN"  # 여기에 실제 토큰을 입력하세요
}
url = "https://geocode-api.gimi9.com/region"
response = requests.get(url, params=params)
print(response.json())
        

응답 예제

[
    {
        "success": true,
        "type": "hd",
        "code": "1114055000",
        "name": "명동",
        "wkt": "POLYGON ((126.984159 37.553060, 126.982984 37.555564, ...))",
        "yyyymm": "202506"
    },
    {
        "success": true,
        "type": "hd",
        "code": "4111760000",
        "name": "광교1동",
        "wkt": "POLYGON ((127.062152 37.296292, 127.065016 37.291754, ...))",
        "yyyymm": "202506"
    }
]

응답 필드 설명 (배열)

영역 유형 설명

• h1: 광역시도 (예: 11(서울특별시), 41(경기도))
• h23: 시군구 (예: 종로구(11140), 수원시 영통구(41117))
• hd: 행정동 (예: 명동(1114055000), 영통동(4111760000))

행정동 이력

지정된 좌표를 기준으로 행정동 이력 정보를 조회합니다.

요청 파라미터

요청 예제

GET https://geocode-api.gimi9.com/hd_history?x=127.075074&y=37.143834&token=YOUR_API_TOKEN

응답 예제

[
  {
    "hd_cd": "4137052300",
    "hd_nm": "대원1동",
    "hd_en": "Daewon1(il)-dong",
    "from_yyyymm": "202312",
    "to_yyyymm": "202504"
  },
  {
    "hd_cd": "4137057000",
    "hd_nm": "대원동",
    "hd_en": "Daewon-dong",
    "from_yyyymm": "202305",
    "to_yyyymm": "202311"
  }
]

응답 필드 설명

토큰 통계

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

요청 파라미터

요청 예제

GET https://geocode-api.gimi9.com/token/stats?token=YOUR_API_TOKEN

응답 예제

{
  "total_requests": 288945,
  "last_month_requests": 949,
  "monthly_quota": 100000000,
  "remaining_quota": 99999051,
  "daily_quota": 10000000,
  "daily_requests": 3,
  "remaining_daily_quota": 9999997,
  "last_request_date": "2025-06-03T09:54:20.450054+09:00"
}

응답 필드 설명