API 참조

단일 IP 조회의 엔드포인트, 응답 형식 및 HTTP 오류.

엔드포인트

기본 URLhttps://api.ipquery.ioAPI 키 없음

호출자 IP

GET/기본값: text/plain

요청을 보낸 주소를 반환합니다. 브라우저 fetch는 브라우저 연결을 식별하며, 서버 측 fetch는 서버를 식별합니다.

요청

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/?format=json"

단일 IP

GET/:ip기본값: application/json

경로에 IPv4 또는 IPv6 주소 하나를 넣으세요. 결과는 호출자의 연결과 관계없이 해당 주소를 설명합니다.

요청

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/1.1.1.1"

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/2606:4700:4700::1111"

HTTPS를 사용하세요. 다음을 추가하세요: ?format=json (애플리케이션에 구조화된 내 IP 결과가 필요한 경우).

응답 형식

응답 표현 형식은 format 쿼리 값으로 선택하세요.

JSON: ?format=jsonapplication/json
XML: ?format=xmlapplication/xml
YAML: ?format=yamlapplication/x-yaml
텍스트: ?format=texttext/plain

텍스트는 주소만 반환합니다. JSON, XML 및 YAML은 구조화된 조회 결과를 반환합니다.

오류 및 일괄 조회

조회 성공 결과를 읽기 전에 HTTP 상태를 확인하세요. 오류 본문은 식별 가능한 다음 형식을 따릅니다: format 쿼리; 형식을 생략하거나 지원하지 않는 형식을 지정하면 일반 텍스트가 반환됩니다.

유효하지 않은 주소

HTTP 404

주소 구문을 확인하세요. 경로에는 IPv4 또는 IPv6 주소 하나만 입력할 수 있습니다.

요청

curl -i "https://api.ipquery.io/not-an-ip?format=json"

HTTP 404

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error":"IP address not-an-ip not found"}

지원하지 않는 형식

HTTP 400

json, xml, yaml 또는 text를 사용하세요. CSV는 API 응답 형식이 아닙니다.

요청

curl -i "https://api.ipquery.io/1.1.1.1?format=csv"

HTTP 400

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Invalid format

일괄 조회 비활성화됨

HTTP 400

방문자에는 내 IP 엔드포인트를 사용하거나 주소 하나를 요청하세요. 같은 일괄 요청을 재시도해도 활성화되지 않습니다.

요청

curl -i "https://api.ipquery.io/1.1.1.1,8.8.8.8?format=json"

HTTP 400

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"Bulk lookups are disabled due to abuse. For your own IP, embed fetch(\"https://api.ipquery.io/?format=json\") in your app, or use a single-IP lookup at https://api.ipquery.io/<ip>."}

실패한 요청 처리

브라우저 GET 요청은 교차 출처 접근을 지원합니다. 네트워크 오류로 거부되는 호출: fetch; HTTP 오류도 응답으로 이행됩니다. 확인할 값: response.ok JSON을 파싱하기 전에 확인하세요.

HTTP 상태 확인

const response = await fetch(
  "https://api.ipquery.io/1.1.1.1?format=json",
  { signal: AbortSignal.timeout(5000) }
);
if (!response.ok) {
  const message = await response.text();
  throw new Error("IPQuery " + response.status + ": " + message);
}
const data = await response.json();
console.log(data.ip);

연결 오류 및 서버 장애

시간 초과 또는 5xx 응답은 IP 레코드가 아닙니다. 명시적인 사용 불가 상태를 유지하고 재시도 횟수를 제한하세요. 업스트림 오류 본문은 텍스트 또는 HTML일 수 있으므로, 모든 응답에 JSON이 포함된다고 가정하지 마세요.

원본에 없는 문자열은 비어 있을 수 있습니다. false 플래그는 불일치이며 안전성 판정이 아닙니다. 필드 정의 읽기

실제 응답

1.1.1.1

실시간 단일 IP 응답

{
  "ip": "1.1.1.1",
  "isp": {
    "asn": "AS13335",
    "org": "Cloudflare, Inc.",
    "isp": "Cloudflare, Inc."
  },
  "location": {
    "country": "Australia",
    "country_code": "AU",
    "city": "Brisbane",
    "state": "Queensland",
    "zipcode": "",
    "latitude": -27.474848400186662,
    "longitude": 153.00996200912815,
    "timezone": "Australia/Brisbane",
    "localtime": "2026-11-03T14:32:36"
  },
  "risk": {
    "is_mobile": false,
    "is_vpn": false,
    "is_tor": false,
    "is_proxy": false,
    "is_datacenter": true,
    "risk_score": 20
  }
}