Official PHP library for IPinfo (IP geolocation and other types of IP data)


IPinfo IPinfo PHP Client Library

This is the official PHP client library for the IP address API, allowing you to lookup your own IP address, or get any of the following details for an IP:

  • IP to Geolocation data (city, region, country, postal code, latitude and longitude)
  • ASN information (ISP or network operator, associated domain name, and type, such as business, hosting or company)
  • Company details (the name and domain of the business that uses the IP address)
  • Carrier information (the name of the mobile carrier and MNC and MCC for that carrier if the IP is used exclusively for mobile traffic)

Check all the data we have for your IP address here.

Getting Started

You'll need an IPinfo API access token, which you can get by singing up for a free account at

The free plan is limited to 50,000 requests per month, and doesn't include some of the data fields such as IP type and company data. To enable all the data fields and additional request volumes see


First download Composer by following the instructions here. After successful installation run the following command.

php composer.phar require ipinfo/ipinfo

Quick Start

require_once __DIR__ . '/vendor/autoload.php';

use ipinfo\ipinfo\IPinfo;

$access_token = '123456789abc';
$client = new IPinfo($access_token);
$ip_address = '';
$details = $client->getDetails($ip_address);

$details->city; // Emeryville
$details->loc; // 37.8342,-122.2900


The IPinfo->getDetails() method accepts an IP address as an optional, positional argument. If no IP address is specified, the API will return data for the IP address from which it receives the request.

$client = new IPinfo();
$ip_address = '';
$details = $client->getDetails($ip_address);
$details->city; // Emeryville
$details->loc; // 37.8342,-122.2900


The IPinfo library can be authenticated with your IPinfo API token, which is passed in as a positional argument. It also works without an authentication token, but in a more limited capacity.

$access_token = '123456789abc';
$client = new IPinfo($access_token);

Details Data

IPinfo->getDetails() will return a Details object that contains all fields listed IPinfo developer docs with a few minor additions. Properties can be accessed directly.

$details->hostname; //

Country Name

Details->country_name will return the country name, as supplied by the countries.json file. See below for instructions on changing that file for use with non-English languages. Details->country will still return country code.

$details->country; // US
$details->country_name; // United States

Longitude and Latitude

Details->latitude and Details->longitude will return latitude and longitude, respectively, as strings. Details->loc will still return a composite string of both values.

$details->loc; // 34.0293,-118.3570
$details->latitude; // 34.0293
$details->longitude; // -118.3570

Accessing all properties

Details->all will return all details data as a dictionary.

    'asn': {  'asn': 'AS20001',
               'domain': '',
               'name': 'Time Warner Cable Internet LLC',
               'route': '',
               'type': 'isp'},
    'city': 'Los Angeles',
    'company': {   'domain': '',
                   'name': 'Time Warner Cable Internet LLC',
                   'type': 'isp'},
    'country': 'US',
    'country_name': 'United States',
    'hostname': '',
    'ip': '',
    'loc': '34.0293,-118.3570',
    'latitude': '34.0293',
    'longitude': '-118.3570',
    'phone': '323',
    'postal': '90016',
    'region': 'California'


In-memory caching of Details data is provided by default via the sabre/cache library. LRU (least recently used) cache-invalidation functionality has been added to the default TTL (time to live). This means that values will be cached for the specified duration; if the cache's max size is reached, cache values will be invalidated as necessary, starting with the oldest cached value.

Modifying cache options

Default cache TTL and maximum size can be changed by setting values in the $settings argument array.

  • Default maximum cache size: 4096 (multiples of 2 are recommended to increase efficiency)
  • Default TTL: 24 hours (in seconds)
$access_token = '123456789abc';
$settings = ['cache_maxsize' => 30, 'cache_ttl' => 128];
$client = new IPinfo($access_token, $settings);

Using a different cache

It's possible to use a custom cache by creating a child class of the CacheInterface class and passing this into the handler object with the cache keyword argument. FYI this is known as the Strategy Pattern.

$access_token = '123456789abc';
$settings = ['cache' => $my_fancy_custom_cache];
$client = new IPinfo($access_token, $settings);

Disabling the cache

You may disable the cache by passing in a cache_disabled key in the settings:

$access_token = '123456789abc';
$settings = ['cache_disabled' => true];
$client = new IPinfo($access_token, $settings);

Overriding HTTP Client options

The IPinfo client constructor accepts a timeout key which is the request timeout in seconds.

For full flexibility, a guzzle_opts key is accepted which accepts an associative array which is described in Guzzle Request Options. Options set here will override any custom settings set by the IPinfo client internally in case of conflict, including headers.

Batch Operations

Looking up a single IP at a time can be slow. It could be done concurrently from the client side, but IPinfo supports a batch endpoint to allow you to group together IPs and let us handle retrieving details for them in bulk for you.

$access_token = '123456789abc';
$client = new IPinfo($access_token);
$ips = ['', '', ''];
$results = $client->getBatchDetails($ips);
echo $results['']; // AU

The input size is not limited, as the interface will chunk operations for you behind the scenes.

Please see the official documentation for more information and limitations.


When looking up an IP address, the response object includes a Details->country_name attribute which includes the country name based on American English. It is possible to return the country name in other languages by setting the countries_file keyword argument when creating the IPinfo object.

The file must be a .json file with the following structure:

 "BD": "Bangladesh",
 "BE": "Belgium",
 "BF": "Burkina Faso",
 "BG": "Bulgaria"

Other Libraries

There are official IPinfo client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails and Laravel. There are also many third party libraries and integrations available for our API.

About IPinfo

Founded in 2013, IPinfo prides itself on being the most reliable, accurate, and in-depth source of IP address data available anywhere. We process terabytes of data to produce our custom IP geolocation, company, carrier, privacy, hosted domains and IP type data sets. Our API handles over 40 billion requests a month for 100,000 businesses and developers.


  • PSR-4 non-compliance warning by composer

    PSR-4 non-compliance warning by composer

    Here is the error I get every time I run composer update.

    Deprecation Notice: Class ipinfo\ipinfo\cache\CacheInterface located in ./vendor/ipinfo/ipinfo/src/cache/Interface.php does not comply with psr-4 autoloading standard. It will not autoload anymore in Composer v2.0. in phar:///usr/local/bin/composer/src/Composer/Autoload/ClassMapGenerator.php:185
    Deprecation Notice: Class ipinfo\ipinfo\cache\DefaultCache located in ./vendor/ipinfo/ipinfo/src/cache/Default.php does not comply with psr-4 autoloading standard. It will not autoload anymore in Composer v2.0. in phar:///usr/local/bin/composer/src/Composer/Autoload/ClassMapGenerator.php:185
    opened by abishekrsrikaanth 8
  • Please update Composer package

    Please update Composer package

    I know that you are working on V2.0.0. This is just to mention that as your Releases page makes the impression that V2.0.0 is released. If so kindly update your Composer Package to V2.0.0.

    opened by umairkhan-dev 7
  • Request: New Map feature to be added

    Request: New Map feature to be added


    I really love IP info and recently you guys launched: Map IPs:

    Would it be possible to get this in the library? I was thinking of PRing it but unsure if it's more of an "experimental/fun" thing at the moment or if it's something that will stick around and is production ready.

    Kind Regards!

    opened by vekien 5
  • Features of extracting json Not working

    Features of extracting json Not working

    There are some features like directly getting Lattitude with $details->lattitude or $details['lattitude'] is not working, and for$TOKEN This part of feature is not working or I'm unable to get the result using simple php command.

    opened by parvezcs16 5
  • Make caching more easily optional

    Make caching more easily optional

    Right now caching can be modified by a settings key to choose your own cache implementation.

    However it should be easier to disable caching (it should really default to disabling, but that would be a breaking change); currently that requires creating a custom cache implementation which simply does nothing.

    We can either create such an implementation that does nothing, or have a new key like cache_disabled and update cache-using code to check if the cache exists before using it.

    opened by UmanShahzad 4
  •  guzzlehttp/guzzle v7.2

    guzzlehttp/guzzle v7.2


    I want to use this package into my project and my project using guzzlehttp/guzzle v7.2 and your package is require a guzzlehttp/guzzle v ^6.3 so I am unable to import package via composer

    can you please update your package at packagist?


    opened by usamawaleed 3
  • Resolves issue #39

    Resolves issue #39

    Changed log

    • Resolves issue #39.
    • After fixing the issue, the sample codes are worked now. And the fixed sample codes are as follows:
    peterli@peterli-Virtual-Machine:~$ psysh
    Psy Shell v0.11.2 (PHP 8.1.4 — cli) by Justin Hileman
    >>> require_once __DIR__ . '/vendor/autoload.php'
    => Composer\Autoload\ClassLoader {#2661}
    >>> use ipinfo\ipinfo\IPinfo;
    >>> $access_token = '123456789abc';
    => "123456789abc"
    >>> $client = new IPinfo($access_token);
    => ipinfo\ipinfo\IPinfo {#2674
         +access_token: "123456789abc",
         +cache: ipinfo\ipinfo\cache\DefaultCache {#2676
           +maxsize: 4096,
           +ttl: 86400,
         +countries: [
           "BD" => "Bangladesh",
           "BE" => "Belgium",
           "BF" => "Burkina Faso",
           "BG" => "Bulgaria",
           "BA" => "Bosnia and Herzegovina",
           "BB" => "Barbados",
         +"settings": [],
    opened by peter279k 2
  • Token Referrer restriction with PHP Lib

    Token Referrer restriction with PHP Lib

    When using a Domainname Referrer restriction on my token, the PHP library fails to fetch user details with an error

    400 Bad Request

    I assume this is because my script runs Serverside hence not having a referrer http header.

    Any ideas how to overcome this? Like can I force pass a referrer serverside to the IPinfo Library?

    opened by oliveratgithub 2
  • PHP 8 Support

    PHP 8 Support

    Unable to download if you have PHP 8

    Output below:

    Problem 1 - ipinfo/ipinfo[dev-master, v2.0.0] require php ~7.0 -> your php version (8.0.0) does not satisfy that requirement. - ipinfo/ipinfo 2.0.x-dev is an alias of ipinfo/ipinfo dev-master and thus requires it to be installed too. - Root composer.json requires ipinfo/ipinfo ^2.0.0 -> satisfiable by ipinfo/ipinfo[v2.0.0, 2.0.x-dev (alias of dev-master)].

    opened by adnansyedimadi 2
  • use this library without composer

    use this library without composer

    Hi I want to use it without the composer. I tried to add files with require_once function nut it does not work. example: require_once('ipinfo/src/IPinfo.php') can you help me?

    opened by mrmmg 2
  • [fix] correct PHP version is 7.0 minimum

    [fix] correct PHP version is 7.0 minimum

    It's stated the package works for PHP 5.6, however, in the code you use PHP 7.0+ functionality, for example:

    • coalesce operators ??, such as
    $maxsize = $settings['cache_maxsize'] ?? self::CACHE_MAXSIZE;
    • scalar types in function declarations, such as:
    public function set(string $name, $value)
    opened by rvalitov 2
IP address API: geolocation, VPN detection, company data and more. Serving over 40 billion API requests a month for 500,000+ businesses and developers.
Free database of geographic place names and corresponding geospatial data

FreeGeoDB Free database of geographic place names and corresponding geospatial data Entities airports cities countries (admin-0) lakes ports railroads 1.6k Dec 15, 2022
A weather data tile generator for digital maps using the Web Mercator projection

Weather data tile generator for Web Mercator maps This is a weather data tile generator for digital maps, which is compatible with Leaflet and in gene

null 2 Aug 11, 2022
Geo-related tools PHP 5.4+ library built atop Geocoder and React libraries

Geotools Geotools is a PHP geo-related library, built atop Geocoder and React libraries. Features Batch geocode & reverse geocoding request(s) in seri

The League of Extraordinary Packages 1.3k Dec 27, 2022
PHP library to easily get static image from French Cadastral Government map with markers and lines.

PHP French Cadastral Map Static API PHP library to easily get static image from French Cadastral Government map with markers and lines. Map source : c

Franck Alary 6 Nov 29, 2022
PHP library to easily get static image from OpenStreetMap (OSM) with markers and lines.

PHP OpenStreetMap Static API PHP library to easily get static image from OpenStreetMap with markers and lines. ✨ Supporting ⭐ Star this repository to

Franck Alary 34 Jan 2, 2023
ESRI ShapeFile library for PHP

shapefile ShapeFile library for PHP Features Currently the 2D and 3D variants except MultiPatch of the ShapeFile format as defined in https://www.esri

phpMyAdmin 23 Jun 29, 2022
The most featured Geocoder library written in PHP.

Geocoder Important: You are browsing the documentation of Geocoder 4.x. Documentation for version 3.x is available here: Geocoder 3.x documentation. D

Geocoder 3.9k Jan 2, 2023
Simple Yet Powerful Geo Library for PHP

phpgeo - A Simple Geo Library for PHP phpgeo provides abstractions to geographical coordinates (including support for different ellipsoids) and allows

Marcus Jaschen 1.4k Dec 27, 2022
PHP library to access the OpenCage geocoding API

OpenCage Geocoding API Library for PHP A PHP library to use the OpenCage geocoding API. Build Status / Code Quality Overview This library attempts to

OpenCage GmbH 29 Nov 15, 2022
PHP library for determining the physical location of binaries

Bin Locator Library for searching binary files in the operating system. Requirements PHP >= 7.4 Installation Library is available as composer reposito

PHP FFI 8 Jul 27, 2022
GeoSpatial integration on Laravel 5.2+ that supports MySQL and PostgreSQL.

Features GeoSpatial integration on Laravel 5.2+: Create geospatial columns using Schema and migrations Save and retrieve geospatial attributes using d

Eleven 47 Dec 22, 2022
Use: [i] to share item and name in hand, [coor] to share you current coordinates

General Now you can share your Coordinates and Item with Prefix Example if you type [i] in message, later it will be automatically replaced into the n

ItsRealNise 7 Oct 15, 2021
Generate and display maps without external services or compromising on privacy.

Generate and display maps without external services or compromising on privacy.

null 144 Dec 29, 2022
PHP extension for geospatial rendering with Mapnik

PHP7 Mapnik Introduction This project is an extension for PHP 7 that enables geospatial rendering with Mapnik. Create tile generation scripts, dynamic

Garrett Johnson 20 Dec 14, 2022
PHP Extension to handle common geospatial functions.

geospatial - PHP Geospatial Extension PHP Extension to handle common geospatial functions. The extension currently has implementations of the Haversin

PHP Geospatial, putting the Elephpant on your globe 56 Dec 29, 2022
GeoJSON implementation for PHP

GeoJson PHP Library This library implements the GeoJSON format specification. The GeoJson namespace includes classes for each data structure defined i

Jeremy Mikola 274 Dec 17, 2022
GeoLocation-Package - This package helps you to know the current language of the user, the country from which he is browsing, the currency of his country, and also whether he is using it vpn

GeoLocation in PHP (API) ?? ?? ?? This package helps you to know a lot of information about the current user by his ip address ?? ?? ?? This package h

Abdullah Karam 4 Dec 8, 2022
cybercog 996 Dec 28, 2022