Geoip2

인증된 제출자

geoip2/geoip2

제출자 이우진

최신 vv3.4.0라이센스 Apache-2.0배포 2026년 10월 9일

MaxMind GeoIP PHP API

GitHub

GeoIP PHP API

설명

이 패키지는 GeoIP와 GeoLite의 웹 서비스 및 데이터베이스를 위한 API를 제공합니다.

Composer로 설치

이 패키지는 Composer로 설치하는 것을 권장합니다.

Composer 다운로드

프로젝트의 루트 디렉터리에서 다음 명령을 실행하여 Composer를 다운로드합니다.

curl -sS https://getcomposer.org/installer | php

실행 후 프로젝트 디렉터리에 composer.phar 파일이 생성됩니다.

의존성 설치

프로젝트 루트에서 다음 명령을 실행합니다.

php composer.phar require geoip2/geoip2:^3.4.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;

// This creates the Reader object, which should be reused across
// lookups.
$cityDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-City.mmdb');

// Replace "city" with the appropriate method for your database, e.g.,
// "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;

// This creates the Reader object, which should be reused across
// lookups.
$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;

// This creates the Reader object, which should be reused across
// lookups.
$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;

// This creates the Reader object, which should be reused across
// lookups.
$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;

// This creates the Reader object, which should be reused across
// lookups.
$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;

// This creates the Reader object, which should be reused across
// lookups.
$enterpriseDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-Enterprise.mmdb');

// Use the ->enterprise method to do a lookup in the Enterprise database
$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;

// This creates the Reader object, which should be reused across
// lookups.
$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;

// This creates a Client object that can be reused across requests.
// Replace "42" with your account ID and "license_key" with your license
// key. Set the "host" to "geolite.info" in the fourth argument options
// array to use the GeoLite web service instead of the GeoIP web
// service. Set the "host" to "sandbox.maxmind.com" in the fourth argument
// options array to use the Sandbox GeoIP web service instead of the
// production GeoIP web service.
$client = new Client(42, 'abcdef123456');

// Replace "city" with the method corresponding to the web service that
// you are using, e.g., "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->geonameId
GeoIp2\Record\Continent - $continent->code 또는 $continent->geonameId
GeoIp2\Record\Country 및 GeoIp2\Record\RepresentedCountry - $country->isoCode 또는 $country->geonameId
GeoIp2\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 사이트를 확인하세요. 장소를 검색하여 지도에서 찾으면 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는 시맨틱 버저닝을 사용합니다.

저작권 및 라이선스

이 소프트웨어는 Apache License, Version 2.0으로 배포되는 자유 소프트웨어입니다.