• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..24-Jul-2020-

src/H24-Jul-2020-1,733664

.php_csH A D23-Jul-20201.2 KiB3634

CHANGELOG.mdH A D23-Jul-20208.2 KiB263188

LICENSEH A D23-Jul-202011.1 KiB203169

README.mdH A D23-Jul-202012.6 KiB402273

composer.jsonH A D23-Jul-2020801 3130

README.md

1# GeoIP2 PHP API #
2
3## Description ##
4
5This package provides an API for the GeoIP2
6[web services](http://dev.maxmind.com/geoip/geoip2/web-services) and
7[databases](http://dev.maxmind.com/geoip/geoip2/downloadable). The API also
8works with the free
9[GeoLite2 databases](http://dev.maxmind.com/geoip/geoip2/geolite2/).
10
11## Install via Composer ##
12
13We recommend installing this package with [Composer](http://getcomposer.org/).
14
15### Download Composer ###
16
17To download Composer, run in the root directory of your project:
18
19```bash
20curl -sS https://getcomposer.org/installer | php
21```
22
23You should now have the file `composer.phar` in your project directory.
24
25### Install Dependencies ###
26
27Run in your project root:
28
29```
30php composer.phar require geoip2/geoip2:~2.0
31```
32
33You should now have the files `composer.json` and `composer.lock` as well as
34the directory `vendor` in your project directory. If you use a version control
35system, `composer.json` should be added to it.
36
37### Require Autoloader ###
38
39After installing the dependencies, you need to require the Composer autoloader
40from your code:
41
42```php
43require 'vendor/autoload.php';
44```
45
46## Install via Phar ##
47
48Although we strongly recommend using Composer, we also provide a
49[phar archive](http://php.net/manual/en/book.phar.php) containing most of the
50dependencies for GeoIP2. Our latest phar archive is available on
51[our releases page](https://github.com/maxmind/GeoIP2-php/releases).
52
53### Install Dependencies ###
54
55In order to use the phar archive, you must have the PHP
56[Phar extension](http://php.net/manual/en/book.phar.php) installed and
57enabled.
58
59If you will be making web service requests, you must have the PHP
60[cURL extension](http://php.net/manual/en/book.curl.php)
61installed to use this archive. For Debian based distributions, this can
62typically be found in the the `php-curl` package. For other operating
63systems, please consult the relevant documentation. After installing the
64extension you may need to restart your web server.
65
66If you are missing this extension, you will see errors like the following:
67
68```
69PHP Fatal error:  Uncaught Error: Call to undefined function MaxMind\WebService\curl_version()
70```
71
72### Require Package ###
73
74To use the archive, just require it from your script:
75
76```php
77require 'geoip2.phar';
78```
79
80## Optional C Extension ##
81
82The [MaxMind DB API](https://github.com/maxmind/MaxMind-DB-Reader-php)
83includes an optional C extension that you may install to dramatically increase
84the performance of lookups in GeoIP2 or GeoLite2 databases. To install, please
85follow the instructions included with that API.
86
87The extension has no effect on web-service lookups.
88
89## IP Geolocation Usage ##
90
91IP geolocation is inherently imprecise. Locations are often near the center of
92the population. Any location provided by a GeoIP2 database or web service
93should not be used to identify a particular address or household.
94
95## Database Reader ##
96
97### Usage ###
98
99To use this API, you must create a new `\GeoIp2\Database\Reader` object with
100the path to the database file as the first argument to the constructor. You
101may then call the method corresponding to the database you are using.
102
103If the lookup succeeds, the method call will return a model class for the
104record in the database. This model in turn contains multiple container
105classes for the different parts of the data such as the city in which the
106IP address is located.
107
108If the record is not found, a `\GeoIp2\Exception\AddressNotFoundException`
109is thrown. If the database is invalid or corrupt, a
110`\MaxMind\Db\InvalidDatabaseException` will be thrown.
111
112See the API documentation for more details.
113
114### City Example ###
115
116```php
117<?php
118require_once 'vendor/autoload.php';
119use GeoIp2\Database\Reader;
120
121// This creates the Reader object, which should be reused across
122// lookups.
123$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-City.mmdb');
124
125// Replace "city" with the appropriate method for your database, e.g.,
126// "country".
127$record = $reader->city('128.101.101.101');
128
129print($record->country->isoCode . "\n"); // 'US'
130print($record->country->name . "\n"); // 'United States'
131print($record->country->names['zh-CN'] . "\n"); // '美国'
132
133print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota'
134print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN'
135
136print($record->city->name . "\n"); // 'Minneapolis'
137
138print($record->postal->code . "\n"); // '55455'
139
140print($record->location->latitude . "\n"); // 44.9733
141print($record->location->longitude . "\n"); // -93.2323
142
143```
144
145### Anonymous IP Example ###
146
147```php
148<?php
149require_once 'vendor/autoload.php';
150use GeoIp2\Database\Reader;
151
152// This creates the Reader object, which should be reused across
153// lookups.
154$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-Anonymous-IP.mmdb');
155
156$record = $reader->anonymousIp('128.101.101.101');
157
158if ($record->isAnonymous) { print "anon\n"; }
159print($record->ipAddress . "\n"); // '128.101.101.101'
160
161```
162
163### Connection-Type Example ###
164
165```php
166<?php
167require_once 'vendor/autoload.php';
168use GeoIp2\Database\Reader;
169
170// This creates the Reader object, which should be reused across
171// lookups.
172$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-Connection-Type.mmdb');
173
174$record = $reader->connectionType('128.101.101.101');
175
176print($record->connectionType . "\n"); // 'Corporate'
177print($record->ipAddress . "\n"); // '128.101.101.101'
178
179```
180
181### Domain Example ###
182
183```php
184<?php
185require_once 'vendor/autoload.php';
186use GeoIp2\Database\Reader;
187
188// This creates the Reader object, which should be reused across
189// lookups.
190$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-Domain.mmdb');
191
192$record = $reader->domain('128.101.101.101');
193
194print($record->domain . "\n"); // 'umn.edu'
195print($record->ipAddress . "\n"); // '128.101.101.101'
196
197```
198
199### Enterprise Example ###
200
201```php
202<?php
203require_once 'vendor/autoload.php';
204use GeoIp2\Database\Reader;
205
206// This creates the Reader object, which should be reused across
207// lookups.
208$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-Enterprise.mmdb');
209
210// Use the ->enterprise method to do a lookup in the Enterprise database
211$record = $reader->enterprise('128.101.101.101');
212
213print($record->country->confidence . "\n"); // 99
214print($record->country->isoCode . "\n"); // 'US'
215print($record->country->name . "\n"); // 'United States'
216print($record->country->names['zh-CN'] . "\n"); // '美国'
217
218print($record->mostSpecificSubdivision->confidence . "\n"); // 77
219print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota'
220print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN'
221
222print($record->city->confidence . "\n"); // 60
223print($record->city->name . "\n"); // 'Minneapolis'
224
225print($record->postal->code . "\n"); // '55455'
226
227print($record->location->accuracyRadius . "\n"); // 50
228print($record->location->latitude . "\n"); // 44.9733
229print($record->location->longitude . "\n"); // -93.2323
230
231```
232
233### ISP Example ###
234
235```php
236<?php
237require_once 'vendor/autoload.php';
238use GeoIp2\Database\Reader;
239
240// This creates the Reader object, which should be reused across
241// lookups.
242$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-ISP.mmdb');
243
244$record = $reader->isp('128.101.101.101');
245
246print($record->autonomousSystemNumber . "\n"); // 217
247print($record->autonomousSystemOrganization . "\n"); // 'University of Minnesota'
248print($record->isp . "\n"); // 'University of Minnesota'
249print($record->organization . "\n"); // 'University of Minnesota'
250
251print($record->ipAddress . "\n"); // '128.101.101.101'
252
253```
254
255## Web Service Client ##
256
257### Usage ###
258
259To use this API, you must create a new `\GeoIp2\WebService\Client`
260object with your `$accountId` and `$licenseKey`, then you call the method
261corresponding to a specific end point, passing it the IP address you want to
262look up.
263
264If the request succeeds, the method call will return a model class for the end
265point you called. This model in turn contains multiple record classes, each of
266which represents part of the data returned by the web service.
267
268If there is an error, a structured exception is thrown.
269
270See the API documentation for more details.
271
272### Example ###
273
274```php
275<?php
276require_once 'vendor/autoload.php';
277use GeoIp2\WebService\Client;
278
279// This creates a Client object that can be reused across requests.
280// Replace "42" with your account ID and "license_key" with your license
281// key.
282$client = new Client(42, 'abcdef123456');
283
284// Replace "city" with the method corresponding to the web service that
285// you are using, e.g., "country", "insights".
286$record = $client->city('128.101.101.101');
287
288print($record->country->isoCode . "\n"); // 'US'
289print($record->country->name . "\n"); // 'United States'
290print($record->country->names['zh-CN'] . "\n"); // '美国'
291
292print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota'
293print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN'
294
295print($record->city->name . "\n"); // 'Minneapolis'
296
297print($record->postal->code . "\n"); // '55455'
298
299print($record->location->latitude . "\n"); // 44.9733
300print($record->location->longitude . "\n"); // -93.2323
301
302```
303
304## Values to use for Database or Array Keys ##
305
306**We strongly discourage you from using a value from any `names` property as
307a key in a database or array.**
308
309These names may change between releases. Instead we recommend using one of the
310following:
311
312* `GeoIp2\Record\City` - `$city->geonameId`
313* `GeoIp2\Record\Continent` - `$continent->code` or `$continent->geonameId`
314* `GeoIp2\Record\Country` and `GeoIp2\Record\RepresentedCountry` -
315  `$country->isoCode` or `$country->geonameId`
316* `GeoIp2\Record\Subdivision` - `$subdivision->isoCode` or `$subdivision->geonameId`
317
318### What data is returned? ###
319
320While many of the end points return the same basic records, the attributes
321which can be populated vary between end points. In addition, while an end
322point may offer a particular piece of data, MaxMind does not always have every
323piece of data for any given IP address.
324
325Because of these factors, it is possible for any end point to return a record
326where some or all of the attributes are unpopulated.
327
328See the
329[GeoIP2 Precision web service docs](http://dev.maxmind.com/geoip/geoip2/web-services)
330for details on what data each end point may return.
331
332The only piece of data which is always returned is the `ipAddress`
333attribute in the `GeoIp2\Record\Traits` record.
334
335## Integration with GeoNames ##
336
337[GeoNames](http://www.geonames.org/) offers web services and downloadable
338databases with data on geographical features around the world, including
339populated places. They offer both free and paid premium data. Each
340feature is unique identified by a `geonameId`, which is an integer.
341
342Many of the records returned by the GeoIP2 web services and databases
343include a `geonameId` property. This is the ID of a geographical feature
344(city, region, country, etc.) in the GeoNames database.
345
346Some of the data that MaxMind provides is also sourced from GeoNames. We
347source things like place names, ISO codes, and other similar data from
348the GeoNames premium data set.
349
350## Reporting data problems ##
351
352If the problem you find is that an IP address is incorrectly mapped,
353please
354[submit your correction to MaxMind](http://www.maxmind.com/en/correction).
355
356If you find some other sort of mistake, like an incorrect spelling,
357please check the [GeoNames site](http://www.geonames.org/) first. Once
358you've searched for a place and found it on the GeoNames map view, there
359are a number of links you can use to correct data ("move", "edit",
360"alternate names", etc.). Once the correction is part of the GeoNames
361data set, it will be automatically incorporated into future MaxMind
362releases.
363
364If you are a paying MaxMind customer and you're not sure where to submit
365a correction, please
366[contact MaxMind support](http://www.maxmind.com/en/support) for help.
367
368## Other Support ##
369
370Please report all issues with this code using the
371[GitHub issue tracker](https://github.com/maxmind/GeoIP2-php/issues).
372
373If you are having an issue with a MaxMind service that is not specific
374to the client API, please see
375[our support page](http://www.maxmind.com/en/support).
376
377## Requirements  ##
378
379This library requires PHP 5.4 or greater. This library works and is tested
380with HHVM.
381
382This library also relies on the [MaxMind DB Reader](https://github.com/maxmind/MaxMind-DB-Reader-php).
383
384## Contributing ##
385
386Patches and pull requests are encouraged. All code should follow the PSR-2
387style guidelines. Please include unit tests whenever possible. You may obtain
388the test data for the maxmind-db folder by running `git submodule update
389--init --recursive` or adding `--recursive` to your initial clone, or from
390https://github.com/maxmind/MaxMind-DB
391
392## Versioning ##
393
394The GeoIP2 PHP API uses [Semantic Versioning](http://semver.org/).
395
396## Copyright and License ##
397
398This software is Copyright (c) 2013-2018 by MaxMind, Inc.
399
400This is free software, licensed under the Apache License, Version 2.0.
401
402