Skip to main content

🌍 GeoIP API

apis.how/api/v1/geoip 는 IP 주소 → 국가 / 도시 / ASN(통신사) 해석을 제공하는 중앙 API 예시 경로입니다.

self-hosted 배포에서는 동일한 구조를 apis.${ROOT_DOMAIN}/api/v1/geoip 로 운영할 수 있습니다.

왜 중앙 API 인가​

GeoIP 라이브러리와 데이터베이스(GeoLite2)는 용량이 크고 주기적 갱신이 필요합니다. 이를 한 곳(apis.how) 에서만 관리하고, 각 서비스는 라이브러리/DB 없이 API 토큰만 으로 소비합니다.

  • 데이터베이스·라이브러리·갱신 cron 을 apis.how 한 곳에서 운영
  • 소비 서비스는 .env 토큰만 설정 (별도 인프라 불필요)
  • 결과는 캐시되어 동일 IP 반복 조회가 빠름

사용 대상​

  • 회원·관리자 접속 IP 이력에 지역 정보를 부가하려는 SaaS
  • 방문 통계·이상 접속 분석에 국가/도시/ASN 이 필요한 서비스

인증​

Authorization: Bearer {api-token}. 토큰은 API Access Keys 에서 발급하며 다음 scope 가 필요합니다.

항목값
servicegeoip
abilitygeoip:lookup

엔드포인트​

MethodPath설명
GET/api/v1/geoip/lookup/{ip}단건 조회
POST/api/v1/geoip/lookup배치 조회 (ips[], 최대 100개)

요청 / 응답​

단건​

curl https://apis.how/api/v1/geoip/lookup/8.8.8.8 \
  -H "Authorization: Bearer {api-token}"
{
  "status": "success",
  "data": {
    "ip": "8.8.8.8",
    "found": true,
    "country": "United States",
    "country_code": "US",
    "city": "Mountain View",
    "asn": 15169,
    "asn_org": "Google LLC"
  }
}

배치​

curl -X POST https://apis.how/api/v1/geoip/lookup \
  -H "Authorization: Bearer {api-token}" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"]}'
{ "status": "success", "data": { "results": [ { "ip": "8.8.8.8", "found": true, "country_code": "US", "city": "Mountain View", "asn": 15169, "asn_org": "Google LLC" }, { "...": "..." } ] } }

미해석 IP 는 found: false 와 함께 지역 필드가 null 로 반환됩니다(오류 아님).

에러​

상태코드의미
401auth_requiredBearer 토큰 없음
403(정책)service/ability/IP 정책 거부
422invalid_ipIP 형식 오류

Managed vs Self-Hosted​

Managed Mode​

  • https://apis.how/api/v1/geoip

Self-Hosted Mode​

  • https://apis.${ROOT_DOMAIN}/api/v1/geoip

권장 기본값은 apis.${ROOT_DOMAIN} 입니다.

소비 서비스 설정​

Multi-SaaS Kit 의 GeoIp plugin 을 사용하면 인터페이스에만 의존하여 중앙 API 를 소비합니다.

GEOIP_PROVIDER=api
GEOIP_API_URL=https://apis.how/api/v1/geoip
GEOIP_API_TOKEN={api-token}
GEOIP_API_TIMEOUT=5

API 가 응답하지 않거나 미설정이면 지역 정보 없이 IP 만 표시됩니다(graceful — 서비스 중단 없음).

운영 (Self-Hosted)​

  • MaxMind 계정으로 GeoLite2 데이터베이스를 다운로드해 배치합니다.
  • 주간 자동 갱신: php artisan apis:geoip:update-database (라이선스 키 필요, 미설정 시 갱신 생략).
  • GeoIP 라이브러리는 permissive 라이선스이며, GeoLite2 데이터베이스는 MaxMind 약관에 따릅니다.

관련 문서​