목차
API 데모! 서비스 데모! 리버스 지오코딩 알아보기

지오코더 설명서

geocoder-kr은 한국 주소를 위한 Python 기반 지오코딩 솔루션입니다. 이 솔루션을 사용하면 한국의 주소를 지리적 좌표(위도와 경도)로 변환할 수 있습니다.

특징

  • 한국 주소 체계에 최적화
  • 다양한 주소 형식 지원 (도로명 주소, 지번 주소)
  • 지오코딩 및 리버스 지오코딩
  • 빠르고 정확한 지오코딩 결과
  • 쉬운 설치
  • 간편한 API 사용
  • 매우 적은 리소스 사용
  • 초고속 처리 속도
  • 온프레미스 호스팅 가능
지오코딩

설치

pip install geocoder-kr

데이터 다운로드 (필수)

geocoder-kr이 동작하려면 데이터 파일이 필요합니다.

  1. code 데이터 다운로드
  2. Geocoding 데이터 다운로드
  3. Reverse Geocoding 데이터 다운로드
  4. 다운로드한 파일을 프로젝트 디렉토리에 다음과 같이 복사하세요.
디렉토리 구조 예시 
📂 db                                       [12GB]
├── 📂 code                              [64MB 3개의 파일]
│   ├── 📄 PNU.csv [3MB]
│   ├── 📄 TN_SPRD_RDNM.txt [62MB]
│   └── 📄 h1_h2_code_match.csv [15KB]
├── 📂 rocks                             [3GB 336개의 파일]
│   ├── 📄 000441.sst [961B]
│   ├── 📄 004238.sst [65MB]
│   ├── 📄 004239.sst [65MB]
│   └── 📄 004240.sst [65MB]
└── 📂 rocks-reverse-geocoder            [9GB 348개의 파일]
    ├── 📄 005253.sst [65MB]
    ├── 📄 005254.sst [65MB]
    ├── 📄 005256.sst [65MB]
    └── 📄 005257.sst [65MB]
참고: 위의 디렉토리 구조는 tree-view 유틸리티를 사용하여 제작되었습니다.

사용법 (라이브러리)

from geocoder_kr import geocoder, reverse_geocoder

gc = geocoder.Geocoder()
print(gc.search("서울특별시 송파구 장지동 839-5번지"))

rev_gc = reverse_geocoder.ReverseGeocoder()
print(rev_gc.search(127.11609829941841, 37.546857074590875))

사용법 (API 서버)

실행

uvicorn --host=0.0.0.0 api_fast:app
웹 브라우저로 http://localhost:8000/ 에 접속하면 API 서비스의 기본 페이지가 표시됩니다.

Simple 지오코딩

Request

https://geocode-kr.gimi9.com/geocode?q=서울특별시 송파구 송파대로8길 10

Response

{
  "total_time": 0.007039785385131836,
  "total_count": 1,
  "success_count": 1,
  "fail_count": 0,
  "results": [
    {
      "x": 967118,
      "y": 1942008,
      "z": "05813",
      "hc": "1171064600",
      "lc": "1171010900",
      "rc": "117104169355",
      "bn": "1171010900102530005000001",
      "h1": "서울",
      "rm": "송파대로8길",
      "bm": [
        "송파파인13",
        "송파파인13",
        ""
      ],
      "success": true,
      "errmsg": "",
      "h1_cd": "11",
      "h2_cd": "11710",
      "kostat_h1_cd": "11",
      "kostat_h2_cd": "11240",
      "hash": "송파_송파대로8길_10-0",
      "address": "서울특별시 송파구 송파대로8길 10",
      "addressCls": "ROAD_ADDRESS",
      "toksString": "H1\t서울특별시\nH23\t송파구\nROAD\t송파대로8길\n건번\t10",
      "x_axis": 127.12810603742214,
      "y_axis": 37.476715383128074,
      "inputaddr": "서울특별시 송파구 송파대로8길 10"
    }
  ]
}

여러 개의 주소 지오코딩

여러 주소를 한 번에 지오코딩하는 방법은 간단합니다. 각 주소를 배열에 넣고 POST로 요청하세요.

curl -X 'POST' \
  'https://geocode-kr.gimi9.com/batch_geocode' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "q": [
    "서울특별시 송파구 송파대로8길 10",
    "서울특별시 송파구 양재대로72길 20",
    "서울특별시 구로구 고척로21나길 85-6",
    "서울특별시 노원구 월계로53길 21",
    "서울특별시 서초구 바우뫼로 91"
  ]
}'
import requests

url = 'https://geocode-kr.gimi9.com/batch_geocode'
headers = {
  'accept': 'application/json',
}
data = {
  "q": [
    "서울특별시 송파구 송파대로8길 10",
    "서울특별시 송파구 양재대로72길 20",
    "서울특별시 구로구 고척로21나길 85-6",
    "서울특별시 노원구 월계로53길 21",
    "서울특별시 서초구 바우뫼로 91"
  ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
const axios = require('axios');

const url = 'https://geocode-kr.gimi9.com/batch_geocode';
const headers = {
  'accept': 'application/json',
};
const data = {
  q: [
    "서울특별시 송파구 송파대로8길 10",
    "서울특별시 송파구 양재대로72길 20",
    "서울특별시 구로구 고척로21나길 85-6",
    "서울특별시 노원구 월계로53길 21",
    "서울특별시 서초구 바우뫼로 91"
  ]
};

axios.post(url, data, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Error:', error);
  });

Response

{
  "total_time": 0.008105278015136719,
  "total_count": 5,
  "success_count": 5,
  "fail_count": 0,
  "results": [
    {
      "x": 967118,
      "y": 1942008,
      "z": "05813",
      "hc": "1171064600",
      "lc": "1171010900",
      "rc": "117104169355",
      "bn": "1171010900102530005000001",
      "h1": "서울",
      "rm": "송파대로8길",
      "bm": [
        "송파파인13",
        "송파파인13",
        ""
      ],
      "success": true,
      "errmsg": "",
      "h1_cd": "11",
      "h2_cd": "11710",
      "kostat_h1_cd": "11",
      "kostat_h2_cd": "11240",
      "hash": "송파_송파대로8길_10-0",
      "address": "서울특별시 송파구 송파대로8길 10",
      "addressCls": "ROAD_ADDRESS",
      "toksString": "H1\t서울특별시\nH23\t송파구\nROAD\t송파대로8길\n건번\t10",
      "x_axis": 127.12810603742214,
      "y_axis": 37.476715383128074,
      "inputaddr": "서울특별시 송파구 송파대로8길 10"
    },
    /* 생략... */
  ]
}

리버스 지오코딩

좌표(위도와 경도)에 해당하는 주소를 찾습니다.

리버스 지오코딩

Request

https://geocode-kr.gimi9.com/reverse_geocode/?x=127.12771948485866&y=37.47699735340699

Response

{
  "PNU": "1171010900108390005",
  "yyyymm": "202404",
  "address": "서울특별시 송파구 장지동 839-5번지",
  "success": true,
  "geom": "POLYGON ((127.127924 37.476489, 127.127981 37.476459, 127.127644 37.476489, 127.127639 37.476490, 127.127685 37.476530, 127.127651 37.476725, 127.127651 37.476726, 127.127613 37.476939, 127.127612 37.476946, 127.127607 37.476976, 127.127584 37.477093, 127.127569 37.477158, 127.127557 37.477209, 127.127525 37.477325, 127.127511 37.477371, 127.127510 37.477375, 127.127490 37.477440, 127.127449 37.477554, 127.127438 37.477583, 127.127435 37.477590, 127.127405 37.477667, 127.127356 37.477778, 127.127349 37.477794, 127.127351 37.477794, 127.127351 37.477794, 127.127313 37.477872, 127.127279 37.477941, 127.127186 37.478126, 127.127133 37.478232, 127.127097 37.478309, 127.127081 37.478346, 127.127051 37.478415, 127.127016 37.478499, 127.126984 37.478585, 127.126954 37.478673, 127.126929 37.478752, 127.126923 37.478768, 127.126898 37.478856, 127.126875 37.478944, 127.126852 37.479042, 127.126821 37.479206, 127.126785 37.479442, 127.126692 37.479489, 127.127058 37.479583, 127.127005 37.479503, 127.127033 37.479300, 127.127047 37.479210, 127.127059 37.479147, 127.127071 37.479088, 127.127085 37.479023, 127.127100 37.478961, 127.127117 37.478899, 127.127134 37.478838, 127.127152 37.478777, 127.127173 37.478715, 127.127193 37.478655, 127.127216 37.478594, 127.127239 37.478534, 127.127268 37.478466, 127.127298 37.478398, 127.127331 37.478328, 127.127446 37.478168, 127.127571 37.477916, 127.127598 37.477781, 127.127645 37.477667, 127.127709 37.477494, 127.127839 37.477158, 127.127877 37.476951, 127.127862 37.476840, 127.127914 37.476550, 127.127924 37.476489))",
  "errmsg": ""
}

API 문서

RESTful API를 설계, 문서화, 테스트하기 위한 Swagger 기반의 도구를 제공합니다.

온라인 문서 보기 Swagger API 문서

주의사항

주의
  • 이 솔루션은 한국 주소에 특화되어 있으므로, 해외 주소에는 사용할 수 없습니다.
  • 정확한 결과를 위해 가능한 한 상세한 주소를 입력하세요.

자주 묻는 질문

하루에 1만건까지 사용할 수 있습니다. 그 이상 필요하면 프로버전(유료)를 사용하세요. gisman@gmail.com으로 문의해 주세요.

매일 데이터를 업데이트 합니다.
오픈소스용 다운로드 파일은 1년에 한 번 배포합니다.

지오코딩은 주소정보 누리집의 여러 공공데이터를 사용합니다.

리버스 지오코딩은 브이월드의 연속지적도와 건물도형 공공데이터를 사용합니다.

지오코딩은 초당 3천 건, 시간당 1천만 건 이상을 처리하며, 리버스 지오코딩 속도 또한 유사합니다.

온프레미스 서버의 워커 수를 조정하면 동시에 처리 가능한 요청 수를 늘릴 수 있습니다.

최저 사양: AWS EC2 t2.micro (1 vCPU, 1GiB 메모리) 수준이면 충분합니다.

권장 사양: 4GB 이상의 RAM. SSD 저장 장치

저장 공간: 약 15GB 필요합니다.

기여

기여를 환영합니다! GitHub 저장소를 포크하고 풀 리퀘스트를 보내주세요. 버그 리포트, 기능 제안, 문서 개선 등 모든 종류의 기여를 환영합니다.

지오코딩이 안 되는 주소가 있으면 알려주세요.

지원 및 문의

문제가 발생하거나 질문이 있으시면 GitHub 이슈를 통해 문의해 주세요.

빠르게 답을 얻으려면 카톡 오픈채팅으로 문의해주세요.

크레딧

  • Meta의 RocksDB를 이용하여 간단한 구조와 빠른 성능을 얻을 수 있었습니다.

상업적 이용

상업적 이용은 엄격히 금지됩니다. 상업적으로 사용하려면 gisman@gmail.com 으로 문의해 주세요.

다음과 같은 경우 자유롭게 사용할 수 있습니다:

  • 개인적 사용: 개인이 비영리 목적으로 소프트웨어를 사용하는 경우
  • 교육 목적: 학교, 대학 등 교육 기관에서 학습 및 연구 목적으로 사용하는 경우
  • 비영리 단체: 자선 단체나 NGO 등이 그들의 미션을 수행하기 위해 사용하는 경우
  • 오픈소스 프로젝트: 다른 비상업적 오픈소스 프로젝트에서 해당 솔루션을 활용하는 경우
  • 정부 기관: 공공 서비스 제공을 위해 정부 기관에서 사용하는 경우
  • 학술 연구: 대학이나 연구소에서 순수 학술 목적으로 사용하는 경우

자세한 내용은 LICENSE 파일을 참조하시기 바랍니다.

마지막 업데이트: 2025년 5월 15일

GitHub에서 보기