API 문서

모든 엔드포인트는 IPv4와 IPv6를 지원하며 가입 없이 사용할 수 있고, API 키를 사용하면 한도가 높아집니다. 기본 URL: https://bgp.cx

빠른 시작

bash

$ curl https://bgp.cx/api/ip/8.8.8.8
{
  "ip": "8.8.8.8",
  "version": 4,
  "country": "United States",
  "country_code": "US",
  "region": "California",
  "timezone": "America/Chicago",
  "isp": "Google LLC",
  "asn": 15169,
  "asn_organization": "Google LLC",
  "network": "8.8.8.0/24"
}

명령줄

curl, wget, PowerShell, HTTPie 등으로 접근하면 자동으로 텍스트를 반환합니다.

명령	설명
curl https://bgp.cx	내 IP
curl -4 https://bgp.cx	IPv4 강제
curl -6 https://bgp.cx	IPv6 강제
curl https://bgp.cx/info	내 IP 상세 정보
curl https://bgp.cx/ip/1.1.1.1	특정 IP 조회
curl https://bgp.cx/ip/github.com	도메인 조회 (자동 해석)
curl https://bgp.cx/asn/4134	ASN 및 프리픽스 조회
wget -qO- https://bgp.cx	wget
irm https://bgp.cx/api/ip	PowerShell

JSON 엔드포인트

GET/api/ip · /api/ip/{ip|domain}

병합된 결과를 JSON으로 반환합니다. 인수가 없으면 요청자 자신을 조회합니다. 이전 경로 /geoip, /json도 사용할 수 있습니다.

GET/api/lookup?q={ip|domain}

전체 결과: info는 조회 결과, resolved는 도메인 해석 결과입니다.

GET/ip · /jsonip

호출자 IP만 텍스트 또는 {"ip":"…"} 형식으로 반환합니다.

ASN

GET/asn/{asn} · /api/asn/{asn}

ASN의 이름, 도메인, 국가, 네트워크 유형 및 광고된 프리픽스를 반환합니다. family=4 또는 6으로 프로토콜을 제한하고 limit(최대 10000)와 offset으로 페이지를 나눕니다. {asn}은 4134 또는 AS4134 형식 모두 가능합니다.

curl "https://bgp.cx/api/asn/4134?family=4&limit=100&offset=0"

응답 필드

필드	설명
`ip` / `version`	IP 주소 / 4 또는 6
`country` / `country_code`	국가명 / ISO 3166 코드
`region` / `region_code`	시·도 / 주
`city` / `district`	도시 / 구·군
`continent_en` / `country_en` / `region_en` / `city_en` / `district_en`	영문 지명 (요청 언어가 영어가 아니고 데이터에 영문 이름이 있을 때)
`isp` / `organization`	ISP / 조직
`asn` / `asn_organization` / `asn_domain`	AS 번호 / AS 이름 / AS 도메인
`usage_type`	사용 유형: Broadband, Mobile, DataCenter, Cloud, CDN, VPN, Spider, AICrawler, Business, Education 등
`area_code` / `city_code` / `phone_code`	행정구역 코드 / 지역 번호 / 국가 번호
`country_alpha3` / `flag`	ISO 3166-1 alpha-3 코드 / 국기
`currency` / `currency_name` / `languages`	통화 코드 / 통화 이름 / 언어
`network`	네트워크 (CIDR)
`latitude` / `longitude`	대략적인 좌표 (도시와 일치할 때만)
`timezone` / `continent`	시간대 / 대륙
`scope`	비공인 주소 유형: private, loopback, cgnat, reserved 등

데이터가 없는 필드는 결과에 포함되지 않습니다. 반환되는 필드는 API 플랜에 따라 다르며(각 플랜은 데이터베이스 에디션의 필드에 대응, 가격 페이지 참고), 키가 없으면 사이트 설정을 따릅니다.

단일 필드 엔드포인트

GET/ip/{ip}/{field}

값 하나만 텍스트로 반환해 스크립트에 유용합니다. 위 필드 외에 location(전체 위치)과 loc("위도,경도")도 지원합니다. {ip}에 me를 쓰면 내 IP를 조회합니다.

curl https://bgp.cx/ip/me/country

공통 매개변수

매개변수	설명
`lang`	결과 언어: zh-CN, en, ja, de, fr, ru, es, pt-BR
`format`	`json` 또는 `text`로 형식 지정
`pretty`	JSON 보기 좋게 출력
`callback`	JSONP 콜백 이름
`key`	API 키 (조회 전용). `Authorization: Bearer` 헤더 사용 권장

모든 JSON 엔드포인트는 교차 출처 요청을 허용합니다 (Access-Control-Allow-Origin: *).

API 키와 한도

키 없이는 IP별(IPv6는 /64 단위), 키가 있으면 요금제에 따라 계정별로 한도가 적용됩니다. 초과하면 429와 Retry-After 헤더를 반환합니다.

curl -H "Authorization: Bearer ipk_xxx" https://bgp.cx/api/ip/1.1.1.1

속도 제한 및 할당량

API 키가 있는 요청은 계정별로 집계되며, 분당 요청 수와 일일 조회량은 API 플랜(유료 플랜이 없으면 무료 플랜 한도)에 따라 정해지고 0시에 초기화됩니다. 키 없는 요청은 IP(IPv6는 /64)별로 분당 요청 수가 제한되며, 사이트에서 일일 횟수도 제한할 수 있습니다. 초과하면 429를 반환하고 Retry-After에 대기할 초가 들어 있습니다.

응답 헤더	설명
`X-RateLimit-Limit`	분당 허용 요청 수
`X-Quota-Limit`	일일 조회량 (무제한이면 없음)
`X-Quota-Remaining`	오늘 남은 조회 수

데이터베이스 다운로드

GET/api/databases

에디션 목록입니다. <code>editions</code>에는 공개된 모든 에디션과 필드가, API 키를 함께 보내면 <code>downloads</code>에 다운로드 가능한 에디션과 파일(이름, 형식, 크기, SHA-256, 빌드 시각)이 포함됩니다.

GET/dl/{file}

구매한 에디션의 파일을 내려받습니다. {file}은 파일명입니다(예: ipdb-insight.mmdb, ipdb-insight-v4.xdb). API 키는 Authorization: Bearer 헤더로 보내세요. Range 이어받기를 지원하며 다시 집계되지 않습니다.

curl -LOJ -C - -H "Authorization: Bearer ipk_xxx" https://bgp.cx/dl/ipdb-insight.mmdb

계정은 본인 전용입니다. 하루에 다운로드할 수 있는 네트워크(IPv4 주소 / IPv6 /64) 수가 제한되며, 웹에서 발급한 링크는 발급된 네트워크에서만 유효합니다.

오프라인 DB의 필드, 파일 형식, 코드 예제는 데이터베이스 문서를 참고하세요.

경로 및 WAF

모든 조회와 다운로드는 고정 접두사를 사용하므로 WAF / CDN에서 경로별 허용 목록이나 캐시 규칙을 설정할 수 있습니다. 호환성을 위해 /{ip} 같은 루트 경로도 동작하며(브라우저는 /ip/로 이동), 관리자가 끌 수 있습니다.

경로 접두사	설명
`/ip/`	IP / 도메인 조회 페이지, 텍스트, 단일 필드
`/asn/`	ASN 페이지 및 텍스트
`/api/`	JSON API (스크립트가 자주 호출하므로 챌린지를 걸지 마세요)
`/dl/`	데이터베이스 파일 다운로드 (용량이 크므로 캐시하지 마세요)

오류

상태 코드	의미
`400`	잘못된 IP 또는 도메인, 혹은 해석할 수 없는 도메인
`401`	잘못된 API 키 또는 다운로드 시 인증 정보 없음
`403`	데이터베이스 권한이 없거나 횟수·네트워크 수 한도 초과
`404`	찾을 수 없음
`429`	요청이 너무 많음

오류 형식은 {"error":"…","code":400}이며 터미널에는 error: … 텍스트로 반환합니다.