데이터베이스 문서

오프라인 DB는 이 사이트의 조회와 같은 데이터입니다. 직접 운영하는 서버에 배포해 로컬에서 조회하므로 네트워크가 필요 없고 호출 횟수 제한도 없습니다. 모든 에디션은 mmdb와 xdb 두 가지 형식으로 제공되며 IPv4와 IPv6를 모두 포함합니다.

• mmdb: 파일 하나에 IPv4와 IPv6가 모두 들어 있고 모든 필드(중국어·영어 이름)를 포함합니다. 구조가 GeoIP2-City와 호환되므로 기존 mmdb 라이브러리로 바로 읽을 수 있습니다.
• xdb: IPv4와 IPv6가 각각 별도 파일입니다. 각 레코드는 |로 구분된 18개 구간의 텍스트로, 용량이 작고 조회가 빨라 트래픽이 많은 서비스에 적합합니다.
• 매월 1일에 업데이트됩니다. 에디션별 파일 이름은 고정되어 있어 파일만 교체하면 업그레이드됩니다.

파일과 에디션

파일 이름은 에디션 코드로 정해집니다. 예: ipdb-enterprise

에디션마다 포함된 필드가 다릅니다. 아래 표의 ‘포함 에디션’ 열이나 다운로드의 비교표를 참고하세요.

필드

mmdb 경로는 점으로 계층을, [0]은 배열의 첫 항목을 뜻합니다. xdb 위치는 18개 구간 지역 텍스트에서 몇 번째 구간인지이며, ‘—’는 xdb에 없는 필드입니다. 예시는 42.203.32.1의 실제 레코드입니다.

위치

네트워크 / ASN

영문 이름

국제 정보

mmdb 형식

mmdb 구조는 GeoIP2-City와 호환됩니다. continent, country, subdivisions, city, location은 표준 구조와 같고 이름은 zh-CN과 en 두 언어로 제공됩니다. ISP, ASN, 사용 유형은 traits에, 구·행정구역 코드 등 확장 필드는 extra에 있습니다.

42.203.32.1의 전체 필드 레코드입니다(필드가 적은 에디션은 그중 일부만 포함):

{
  "continent": { "code": "AS", "names": { "en": "Asia", "zh-CN": "亚洲" } },
  "country": { "iso_code": "CN", "names": { "en": "China", "zh-CN": "中国" } },
  "registered_country": { "iso_code": "CN", "names": { "en": "China", "zh-CN": "中国" } },
  "subdivisions": [ { "names": { "en": "Liaoning", "zh-CN": "辽宁" } } ],
  "city": { "names": { "en": "Anshan", "zh-CN": "鞍山" } },
  "location": { "latitude": 41.089748, "longitude": 122.990852, "time_zone": "Asia/Shanghai" },
  "isp": "中国电信",
  "autonomous_system_number": 4134,
  "autonomous_system_organization": "CHINANET BACKBONE",
  "traits": {
    "isp": "中国电信",
    "autonomous_system_number": 4134,
    "autonomous_system_organization": "CHINANET BACKBONE",
    "domain": "chinatelecom.com.cn",
    "user_type": "broadband"
  },
  "extra": {
    "district": { "en": "Tiedong", "zh-CN": "铁东" },
    "geo_id": "210302",
    "country_alpha3": "CHN",
    "currency_code": "CNY",
    "phone_prefix": "86",
    "languages": "zh-CN",
    "emoji_flag": "🇨🇳",
    "usage_type": "Broadband"
  }
}

메타데이터의 database_type은 IP-City, languages는 zh-CN과 en이며, description에는 에디션과 데이터 월이, build_epoch에는 생성 시각이 들어 있습니다.

xdb 형식

xdb는 IPv4와 IPv6 두 파일입니다(v3 구조, 벡터 인덱스). 각 네트워크 대역은 |로 구분된 18개 구간의 지역 텍스트에 대응하며, 데이터가 없는 구간은 비어 있습니다:

예시(42.203.32.1):

亚洲|中国|辽宁|鞍山|铁东|中国电信|122.990852|41.089748|210302|86||Asia/Shanghai|CNY|AS4134|Broadband|||CN

xdb에는 중국어 이름만 있습니다. 영어 이름, 3자리 국가 코드, 언어, 국기, AS 이름, AS 도메인은 mmdb에만 있습니다. ASN에는 AS 접두사가 붙습니다.

읽기 예제

아래는 언어에 관계없는 의사 코드입니다. mmdb / xdb 라이브러리는 어느 언어에서나 같은 방식입니다: 파일을 열고 IP로 조회한 뒤, 필드 경로나 구간 번호로 값을 읽습니다. 파일 이름은 다운로드한 에디션으로 바꾸세요.

mmdb

아무 mmdb 라이브러리로 파일을 엽니다. IP로 조회하면 중첩된 맵 / 객체가 반환되며, 위 표의 mmdb 경로로 값을 읽습니다. 레코드가 없으면 빈 결과입니다.

db     = open_mmdb("ipdb-enterprise.mmdb")
record = db.lookup("42.203.32.1")

country  = record.country.names["zh-CN"]           // 中国
province = record.subdivisions[0].names["zh-CN"]   // 辽宁
city     = record.city.names["zh-CN"]              // 鞍山
district = record.extra.district["zh-CN"]          // 铁东
isp      = record.traits.isp                       // 中国电信
asn      = record.traits.autonomous_system_number  // 4134
lat, lon = record.location.latitude, record.location.longitude

xdb

v3 구조를 지원하는 xdb 라이브러리로 IP 버전에 맞는 파일(IPv6는 -v6.xdb)을 엽니다. 조회 결과인 지역 텍스트를 |로 18개 구간으로 나눈 뒤 인덱스로 읽습니다(0부터 시작, 위 표의 위치 − 1).

db     = open_xdb("ipdb-enterprise-v4.xdb")
region = db.search("42.203.32.1")
// "亚洲|中国|辽宁|鞍山|铁东|中国电信|122.990852|41.089748|210302|86||Asia/Shanghai|CNY|AS4134|Broadband|||CN"

parts   = split(region, "|")
country = parts[1]    // 中国
city    = parts[3]    // 鞍山
isp     = parts[5]    // 中国电信
asn     = parts[13]   // AS4134

다운로드와 업데이트

플랜을 구매한 후 계정 센터에서 구매한 에디션의 파일을 내려받거나 API 키가 포함된 curl 명령을 복사하세요.

서버에서 내려받기(API 키는 헤더에, 이어받기 지원):

/api/databases는 구매한 에디션의 파일 목록(크기, SHA-256, 생성 시각)을 반환하므로 파일 검증과 새 버전 확인에 쓸 수 있습니다. 자세한 내용은 API 문서를 참고하세요.

데이터는 매월 1일에 업데이트됩니다. 예: 매월 2일 04:00에 최신 버전 자동 내려받기:

0 4 2 * * curl -sfL -o /opt/ipdb/ipdb-enterprise.mmdb.new -H "Authorization: Bearer ipk_xxx" https://bgp.cx/dl/ipdb-enterprise.mmdb && mv /opt/ipdb/ipdb-enterprise.mmdb.new /opt/ipdb/ipdb-enterprise.mmdb

참고 사항

• 데이터가 없는 필드는 mmdb 레코드에 나타나지 않으며 xdb에서는 빈 구간입니다.
• 사설·예약 주소(예: 10.0.0.0/8, 192.168.0.0/16)는 mmdb에 없어 결과가 없으며, xdb에서는 예약으로 표시된 레코드를 반환합니다.
• 위도·경도는 행정구역의 중심점이므로 지역 단위 표시에만 적합하며 정확한 위치 확인에는 쓸 수 없습니다.
• 데이터는 구매한 계정이 라이선스 범위 내에서만 사용할 수 있으며 재판매나 공개 배포는 허용되지 않습니다.