Geoip2
인증된 제출자geoip2/geoip2
MaxMind GeoIP PHP API
GeoIP PHP API
소개
이 패키지는 GeoIP 및 GeoLite 웹 서비스와 데이터베이스를 PHP에서 사용할 수 있는 API를 제공합니다.
Composer로 설치하기
이 패키지는 Composer로 설치하는 것을 권장합니다.
Composer 다운로드
Composer를 내려받으려면 프로젝트 루트 디렉토리에서 다음 명령어를 실행합니다.
curl -sS https://getcomposer.org/installer | php실행이 끝나면 프로젝트 디렉토리에 composer.phar 파일이 생성됩니다.
의존성 설치
프로젝트 루트에서 다음 명령어를 실행합니다.
php composer.phar require geoip2/geoip2:^3.5.0이제 프로젝트 디렉토리에 composer.json, composer.lock 파일과 vendor 디렉토리가 생성됩니다. 버전 관리 시스템을 사용한다면 composer.json을 저장소에 추가해야 합니다.
오토로더 불러오기
의존성을 설치한 뒤에는 코드에서 Composer 오토로더를 불러와야 합니다.
require 'vendor/autoload.php';Phar로 설치하기
Composer 사용을 강력히 권장하지만, GeoIP에 필요한 의존성 대부분을 담은 phar 아카이브도 함께 제공합니다. 최신 phar 아카이브는 릴리스 페이지에서 내려받을 수 있습니다.
의존성 설치
phar 아카이브를 사용하려면 PHP Phar 확장이 설치되어 있고 활성화되어 있어야 합니다.
웹 서비스 요청을 보낼 계획이라면 PHP cURL 확장도 설치되어 있어야 이 아카이브를 사용할 수 있습니다. Debian 계열 배포판에서는 보통 php-curl 패키지로 설치할 수 있습니다. 그 밖의 운영체제에서는 해당 운영체제의 문서를 참고하세요. 확장을 설치한 뒤에는 웹 서버를 재시작해야 할 수도 있습니다.
이 확장이 없으면 다음과 같은 오류가 발생합니다.
PHP Fatal error: Uncaught Error: Call to undefined function MaxMind\WebService\curl_version()
패키지 불러오기
아카이브를 사용하려면 스크립트에서 불러오기만 하면 됩니다.
require 'geoip2.phar';선택 사항: C 확장
MaxMind DB API에는 선택적으로 설치할 수 있는 C 확장이 포함되어 있습니다. 이 확장을 설치하면 GeoIP 또는 GeoLite 데이터베이스의 조회 성능이 크게 향상됩니다. 설치 방법은 해당 API에 포함된 안내를 따르세요.
이 확장은 웹 서비스 조회에는 영향을 주지 않습니다.
IP 위치 정보 사용 시 유의사항
IP 기반 위치 정보는 본질적으로 정확하지 않습니다. 반환되는 위치는 해당 지역의 인구 중심 부근인 경우가 많습니다. GeoIP 데이터베이스나 웹 서비스가 제공하는 위치 정보를 특정 주소나 가구를 식별하는 용도로 사용해서는 안 됩니다.
데이터베이스 리더
사용법
이 API를 사용하려면 데이터베이스 파일 경로를 생성자의 첫 번째 인수로 전달하여 \GeoIp2\Database\Reader 객체를 생성해야 합니다. 그런 다음 사용 중인 데이터베이스에 해당하는 메서드를 호출하면 됩니다.
조회에 성공하면 메서드는 데이터베이스의 해당 레코드를 나타내는 모델 클래스를 반환합니다. 이 모델은 IP 주소가 위치한 도시처럼 데이터의 각 부분을 담는 여러 컨테이너 클래스로 구성되어 있습니다.
레코드를 찾지 못하면 \GeoIp2\Exception\AddressNotFoundException 예외가 발생합니다. 데이터베이스가 유효하지 않거나 손상된 경우에는 \MaxMind\Db\InvalidDatabaseException 예외가 발생합니다.
더 자세한 내용은 API 문서를 참고하세요.
City 예제
<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;
// Reader 객체를 생성합니다. 이 객체는 여러 번의 조회에 걸쳐
// 재사용해야 합니다.
$cityDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-City.mmdb');
// "city"는 사용 중인 데이터베이스에 맞는 메서드(예: "country")로
// 바꿔서 사용하세요.
$record = $cityDbReader->city('128.101.101.101');
print($record->country->isoCode . "\n"); // 'US'
print($record->country->name . "\n"); // 'United States'
print($record->country->names['zh-CN'] . "\n"); // '美国'
print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota'
print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN'
print($record->city->name . "\n"); // 'Minneapolis'
print($record->postal->code . "\n"); // '55455'
print($record->location->latitude . "\n"); // 44.9733
print($record->location->longitude . "\n"); // -93.2323
print($record->traits->network . "\n"); // '128.101.101.101/32'
Anonymous IP 예제
<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;
// Reader 객체를 생성합니다. 이 객체는 여러 번의 조회에 걸쳐
// 재사용해야 합니다.
$anonymousDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-Anonymous-IP.mmdb');
$record = $anonymousDbReader->anonymousIp('128.101.101.101');
if ($record->isAnonymous) { print "anon\n"; }
print($record->ipAddress . "\n"); // '128.101.101.101'
print($record->network . "\n"); // '128.101.101.101/32'
Anonymous Plus 예제
<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;
// Reader 객체를 생성합니다. 이 객체는 여러 번의 조회에 걸쳐
// 재사용해야 합니다.
$anonymousDbReader = new Reader('/usr/local/share/GeoIP/GeoIP-Anonymous-Plus.mmdb');
$record = $anonymousDbReader->anonymousPlus('203.0.113.0');
print($record->anonymizerConfidence . "\n"); // 30
print($record->networkLastSeen . "\n"); // '2025-04-14'
print($record->providerName . "\n"); // 'FooBar VPN'
print($record->ipAddress . "\n"); // '203.0.113.0'
print($record->network . "\n"); // '203.0.113.0/32'
Connection-Type 예제
<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;
// Reader 객체를 생성합니다. 이 객체는 여러 번의 조회에 걸쳐
// 재사용해야 합니다.
$connectionTypeDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-Connection-Type.mmdb');
$record = $connectionTypeDbReader->connectionType('128.101.101.101');
print($record->connectionType . "\n"); // 'Corporate'
print($record->ipAddress . "\n"); // '128.101.101.101'
print($record->network . "\n"); // '128.101.101.101/32'
Domain 예제
<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;
// Reader 객체를 생성합니다. 이 객체는 여러 번의 조회에 걸쳐
// 재사용해야 합니다.
$domainDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-Domain.mmdb');
$record = $domainDbReader->domain('128.101.101.101');
print($record->domain . "\n"); // 'umn.edu'
print($record->ipAddress . "\n"); // '128.101.101.101'
print($record->network . "\n"); // '128.101.101.101/32'
Enterprise 예제
<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;
// Reader 객체를 생성합니다. 이 객체는 여러 번의 조회에 걸쳐
// 재사용해야 합니다.
$enterpriseDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-Enterprise.mmdb');
// Enterprise 데이터베이스를 조회할 때는 ->enterprise 메서드를 사용합니다
$record = $enterpriseDbReader->enterprise('128.101.101.101');
print($record->country->confidence . "\n"); // 99
print($record->country->isoCode . "\n"); // 'US'
print($record->country->name . "\n"); // 'United States'
print($record->country->names['zh-CN'] . "\n"); // '美国'
print($record->mostSpecificSubdivision->confidence . "\n"); // 77
print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota'
print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN'
print($record->city->confidence . "\n"); // 60
print($record->city->name . "\n"); // 'Minneapolis'
print($record->postal->code . "\n"); // '55455'
print($record->location->accuracyRadius . "\n"); // 50
print($record->location->latitude . "\n"); // 44.9733
print($record->location->longitude . "\n"); // -93.2323
print($record->traits->network . "\n"); // '128.101.101.101/32'
ISP 예제
<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;
// Reader 객체를 생성합니다. 이 객체는 여러 번의 조회에 걸쳐
// 재사용해야 합니다.
$ispDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-ISP.mmdb');
$record = $ispDbReader->isp('128.101.101.101');
print($record->autonomousSystemNumber . "\n"); // 217
print($record->autonomousSystemOrganization . "\n"); // 'University of Minnesota'
print($record->isp . "\n"); // 'University of Minnesota'
print($record->organization . "\n"); // 'University of Minnesota'
print($record->ipAddress . "\n"); // '128.101.101.101'
print($record->network . "\n"); // '128.101.101.101/32'
데이터베이스 업데이트
GeoIP Update 프로그램을 사용하면 데이터베이스를 최신 상태로 유지할 수 있습니다. GeoIP Update에 대한 자세한 내용은 개발자 포털에서 확인하세요.
웹 서비스 클라이언트
사용법
이 API를 사용하려면 $accountId와 $licenseKey를 전달하여 \GeoIp2\WebService\Client 객체를 생성해야 합니다.
$client = new Client(42, 'abcdef123456');생성자에 추가 인수를 전달할 수도 있습니다. 세 번째 인수는 이 클라이언트가 생성하는 모델 클래스에서 ->name 메서드를 사용할 때 적용할 언어 우선순위를 지정합니다. 네 번째 인수는 host, timeout 같은 추가 옵션입니다.
예를 들어 GeoIP 웹 서비스 대신 GeoLite 웹 서비스를 호출하려면 다음과 같이 작성합니다.
$client = new Client(42, 'abcdef123456', ['en'], ['host' => 'geolite.info']);운영용 GeoIP 웹 서비스 대신 Sandbox GeoIP 웹 서비스를 호출하려면 다음과 같이 작성합니다.
$client = new Client(42, 'abcdef123456', ['en'], ['host' => 'sandbox.maxmind.com']);클라이언트를 생성한 뒤에는 조회할 IP 주소를 전달하여 원하는 엔드포인트에 해당하는 메서드를 호출하면 됩니다. 예를 들면 다음과 같습니다.
$record = $client->city('128.101.101.101');요청에 성공하면 메서드는 호출한 엔드포인트에 대한 모델 클래스를 반환합니다. 이 모델은 여러 레코드 클래스로 구성되어 있으며, 각 레코드 클래스는 웹 서비스가 반환한 데이터의 일부를 나타냅니다.
오류가 발생하면 구조화된 예외가 발생합니다.
더 자세한 내용은 API 문서를 참고하세요.
예제
<?php
require_once 'vendor/autoload.php';
use GeoIp2\WebService\Client;
// 여러 요청에 걸쳐 재사용할 수 있는 Client 객체를 생성합니다.
// "42"는 본인의 계정 ID로, "license_key"는 본인의 라이선스 키로
// 바꾸세요. GeoIP 웹 서비스 대신 GeoLite 웹 서비스를 사용하려면
// 네 번째 인수인 옵션 배열에서 "host"를 "geolite.info"로 설정합니다.
// 운영용 GeoIP 웹 서비스 대신 Sandbox GeoIP 웹 서비스를 사용하려면
// 네 번째 인수인 옵션 배열에서 "host"를 "sandbox.maxmind.com"으로
// 설정합니다.
$client = new Client(42, 'abcdef123456');
// "city"는 사용 중인 웹 서비스에 해당하는 메서드(예: "country",
// "insights")로 바꿔서 사용하세요.
$record = $client->city('128.101.101.101');
print($record->country->isoCode . "\n"); // 'US'
print($record->country->name . "\n"); // 'United States'
print($record->country->names['zh-CN'] . "\n"); // '美国'
print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota'
print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN'
print($record->city->name . "\n"); // 'Minneapolis'
print($record->postal->code . "\n"); // '55455'
print($record->location->latitude . "\n"); // 44.9733
print($record->location->longitude . "\n"); // -93.2323
print($record->traits->network . "\n"); // '128.101.101.101/32'
데이터베이스 키나 배열 키로 사용할 값
names 속성의 값을 데이터베이스나 배열의 키로 사용하는 것은 강력히 권장하지 않습니다.
이 이름들은 릴리스마다 바뀔 수 있습니다. 대신 다음 값 중 하나를 사용하는 것을 권장합니다.
GeoIp2\Record\City-$city->geonameIdGeoIp2\Record\Continent-$continent->code또는$continent->geonameIdGeoIp2\Record\Country및GeoIp2\Record\RepresentedCountry-$country->isoCode또는$country->geonameIdGeoIp2\Record\Subdivision-$subdivision->isoCode또는$subdivision->geonameId
어떤 데이터가 반환되나요?
많은 엔드포인트가 동일한 기본 레코드를 반환하지만, 실제로 값이 채워질 수 있는 속성은 엔드포인트마다 다릅니다. 또한 엔드포인트가 특정 데이터를 제공하더라도, MaxMind가 모든 IP 주소에 대해 모든 데이터를 보유하고 있는 것은 아닙니다.
이런 이유로 어떤 엔드포인트든 일부 또는 모든 속성이 비어 있는 레코드를 반환할 수 있습니다.
각 엔드포인트가 반환할 수 있는 데이터에 대한 자세한 내용은 GeoIP 웹 서비스 문서를 참고하세요.
항상 반환되는 유일한 데이터는 GeoIp2\Record\Traits 레코드의 ipAddress 속성입니다.
GeoNames 연동
GeoNames는 거주 지역을 포함한 전 세계 지리적 지형지물에 대한 데이터를 웹 서비스와 다운로드 가능한 데이터베이스로 제공합니다. 무료 데이터와 유료 프리미엄 데이터를 모두 제공하며, 각 지형지물은 정수 값인 geonameId로 고유하게 식별됩니다.
GeoIP 웹 서비스와 데이터베이스가 반환하는 레코드 중 상당수에는 geonameId 속성이 포함되어 있습니다. 이 값은 GeoNames 데이터베이스에 등록된 지리적 지형지물(도시, 지역, 국가 등)의 ID입니다.
MaxMind가 제공하는 데이터 중 일부도 GeoNames에서 가져온 것입니다. 지명, ISO 코드 등과 같은 데이터는 GeoNames 프리미엄 데이터 세트를 출처로 합니다.
데이터 문제 신고
IP 주소가 잘못된 위치에 매핑되어 있는 문제를 발견했다면 MaxMind에 수정 요청을 제출해 주세요.
철자 오류와 같은 다른 종류의 오류를 발견했다면 먼저 GeoNames 사이트를 확인해 주세요. 장소를 검색해 GeoNames 지도 화면에서 찾으면 데이터를 수정할 수 있는 여러 링크("move", "edit", "alternate names" 등)를 사용할 수 있습니다. 수정 사항이 GeoNames 데이터 세트에 반영되면 이후 MaxMind 릴리스에 자동으로 포함됩니다.
MaxMind 유료 고객인데 수정 요청을 어디에 제출해야 할지 모르겠다면 MaxMind 지원팀에 문의해 도움을 받으세요.
기타 지원
이 코드와 관련된 모든 이슈는 GitHub 이슈 트래커에 등록해 주세요.
클라이언트 API와 직접 관련이 없는 MaxMind 서비스 문제를 겪고 있다면 지원 페이지를 참고하세요.
요구 사항
이 라이브러리는 PHP 8.1 이상이 필요합니다.
또한 MaxMind DB Reader에 의존합니다.
기여하기
패치와 풀 리퀘스트를 환영합니다. 모든 코드는 PSR-12 스타일 가이드라인을 따라야 하며, 가능하면 단위 테스트를 함께 포함해 주세요. maxmind-db 폴더의 테스트 데이터는 git submodule update --init --recursive를 실행하거나 처음 클론할 때 --recursive 옵션을 추가하여 받을 수 있으며, https://github.com/maxmind/MaxMind-DB 에서도 받을 수 있습니다.
버전 관리
GeoIP PHP API는 유의적 버전(Semantic Versioning)을 따릅니다.
저작권 및 라이선스
이 소프트웨어의 저작권은 MaxMind, Inc.에 있습니다. Copyright (c) 2013-2026 by MaxMind, Inc.
이 소프트웨어는 Apache License, Version 2.0에 따라 라이선스가 부여된 자유 소프트웨어입니다.