Geolocating an IP address using GeoIP or GeoLite web services consists of
configuring a web service client, creating a request, and handling the response.

## Implementation

MaxMind offers and highly recommends using
[official client libraries](/geoip/docs/web-services#client-apis) to access our
geolocation services. If you cannot or do not wish to use our client libraries,
please review our [GeoIP API Documentation page](/geoip/docs/web-services/) for
details on our REST API.

### 1. Install the GeoIP client library

We have a collection of officially supported libraries for you to interact with
the GeoIP and GeoLite APIs:



```csharp
// Install via NuGet
Install-Package MaxMind.GeoIP2
```

```java
// Install via Maven, recommended
<dependency>
  <groupId>com.maxmind.geoip2</groupId>
  <artifactId>geoip2</artifactId>
  <version>5.1.0</version>
</dependency>

// Or install via Gradle
repositories {
  mavenCentral()
}
dependencies {
  implementation 'com.maxmind.geoip2:geoip2:5.1.0'
}
```

```javascript
// Install via npm
npm install @maxmind/geoip2-node

// Or install via yarn
yarn add @maxmind/geoip2-node
```

```php
# Install via Composer
composer require geoip2/geoip2:~3.0
```

```python
# Install via pip
pip install geoip2
```

```ruby
# Install as a gem
gem install maxmind-geoip2

# Or add this to your Gemfile
gem 'maxmind-geoip2'
```



### 2. Create and configure a GeoIP client object

To interact with our API, you need to create a new client object. For this you
will need your MaxMind
[account ID and license key](https://www.maxmind.com/en/accounts/current/license-key).
Our clients also allow you to interact with our GeoLite API, but this requires
additional configuration as demonstrated below:



```csharp
int accountId = 10;
string licenseKey = "LICENSEKEY";

var client = new WebServiceClient(accountId, licenseKey);

// To query the GeoLite web service, you must set the optional `host` parameter
// to `geolite.info`
var client = new WebServiceClient(accountId, licenseKey, host: "geolite.info");
```

```java
int accountId = 10;
String licenseKey = "LICENSEKEY";

WebServiceClient client = new WebServiceClient.Builder(accountId, licenseKey).build();

// To query the GeoLite web service, you must call the `host` method on the
// builder with "geolite.info"
WebServiceClient client = new WebServiceClient.Builder(accountId, licenseKey)
    .host("geolite.info").build();
```

```javascript
import { WebServiceClient } from '@maxmind/geoip2-node';

const accountId = '10';
const licenseKey = 'LICENSEKEY';

const client = new WebServiceClient(accountId, licenseKey);

// To query the GeoLite web service, you must set the optional `host` parameter
const client = new WebServiceClient(accountId, licenseKey, {
  host: 'geolite.info',
});
```

```php
<?php
require_once 'vendor/autoload.php';
use GeoIp2\WebService\Client;

$accountId = 10;
$licenseKey = 'LICENSEKEY';

$client = new Client($accountId, $licenseKey);

// To query the GeoLite web service, you must set the optional `host` argument.
// The third argument specifies the language preferences when using the `->name`
// method on the model classes that this client creates.
$client = new Client($accountId, $licenseKey, ['en'], ['host' => 'geolite.info']);
```

```python
from geoip2.webservice import Client, AsyncClient

account_id = 10
license_key = 'LICENSEKEY'

# If you want to use synchronous requests
client = Client(account_id, license_key)

# To query the GeoLite web service, you must set the "host" keyword argument
# to "geolite.info"
client = Client(account_id, license_key, host='geolite.info')

# Or if you want to use asynchronous requests (requires `import asyncio`)
async_client = AsyncClient(account_id, license_key)

# To query the GeoLite web service, you must set the "host" keyword argument
# to "geolite.info"
async_client = AsyncClient(account_id, license_key, host='geolite.info')
```

```ruby
require 'maxmind/geoip2'

client = MaxMind::GeoIP2::Client.new(
  account_id: 10,
  license_key: 'LICENSEKEY',

  # To use the GeoLite web service instead of GeoIP, set the host
  # parameter to "geolite.info", eg:
  # host: 'geolite.info',
)
```



### 3. Query the desired geolocation service

GeoIP offers 3 services: Insights, City Plus, and Country. GeoLite offers 2
services: City and Country. Each client library has an appropriately named
method for accessing the desired geolocation service.



```csharp
// If you are making multiple requests, a single WebServiceClient
// should be shared across requests to allow connection reuse. The
// class is thread safe.

int accountId = 10;
string licenseKey = "LICENSEKEY";

// Sync
using (var client = new WebServiceClient(accountId, licenseKey))
{
    // You can also use `client.City` or `client.Insights`
    // `client.Insights` is not available to GeoLite users
    var response = client.Country("128.101.101.101");

    Console.WriteLine(response.Country.IsoCode);        // 'US'
    Console.WriteLine(response.Country.Name);           // 'United States'
    Console.WriteLine(response.Country.Names["zh-CN"]); // '美国'
}

// Async
using (var client = new WebServiceClient(accountId, licenseKey))
{
    // You can also use `client.CityAsync` or `client.InsightsAsync`
    // `client.InsightsAsync` is not available to GeoLite users
    var response = await client.CountryAsync("128.101.101.101");

    Console.WriteLine(response.Country.IsoCode);        // 'US'
    Console.WriteLine(response.Country.Name);           // 'United States'
    Console.WriteLine(response.Country.Names["zh-CN"]); // '美国'
}
```

```java
int accountId = 10;
String licenseKey = "LICENSEKEY";

try (WebServiceClient client = new WebServiceClient.Builder(accountId, licenseKey)
        .build()) {

    InetAddress ipAddress = InetAddress.getByName("128.101.101.101");

    // You can also use `client.city` or `client.insights`
    // `client.insights` is not available to GeoLite users
    CountryResponse response = client.country(ipAddress);

    Country country = response.country();
    System.out.println(country.isoCode());            // 'US'
    System.out.println(country.name());               // 'United States'
    System.out.println(country.names().get("zh-CN")); // '美国'
}
```

```javascript
import { WebServiceClient } from '@maxmind/geoip2-node';

const accountId = '10';
const licenseKey = 'LICENSEKEY';

const client = new WebServiceClient(accountId, licenseKey);

// You can also use `client.city` or `client.insights`
// `client.insights` is not available to GeoLite users
client.country('142.1.1.1').then((response) => {
  console.log(response.country.isoCode); // 'CA'
});
```

```php
<?php
require_once 'vendor/autoload.php';
use GeoIp2\WebService\Client;

$accountId = 10;
$licenseKey = 'LICENSEKEY';

$client = new Client($accountId, $licenseKey);

// You can also use `$client->city` or `$client->insights`
// `$client->insights` is not available to GeoLite users
$record = $client->country('128.101.101.101');

print($record->country->isoCode . "\n");
```

```python
# Sync
from geoip2.webservice import Client

account_id = 10
license_key = 'LICENSEKEY'

with Client(account_id, license_key) as client:
  # You can also use `client.city` or `client.insights`
  # `client.insights` is not available to GeoLite users
  response = client.country('128.101.101.101')

  print(response.country.iso_code)

# Async
import asyncio
from geoip2.webservice import AsyncClient

async def main():
  async with AsyncClient(account_id, license_key) as client:
    # You can also use `client.city` or `client.insights`
    # `client.insights` is not available to GeoLite users
    response = await client.country('128.101.101.101')

    print(response.country.iso_code)

asyncio.run(main())
```

```ruby
require 'maxmind/geoip2'

client = MaxMind::GeoIP2::Client.new(
  account_id: 10,
  license_key: 'LICENSEKEY',
)

# You can also use `client.city` or `client.insights`.
# Note that `client.insights` is not available to GeoLite users.
record = client.country('128.101.101.101')

puts record.country.iso_code
```



## Client APIs

You can find a complete list of official and third-party client APIs on the
[web services documentation page](/geoip/docs/web-services#client-apis).

## Command Line (curl) Examples

The web service may be accessed using `curl`, a simple command-line HTTP client.
The `-u` flag is used to pass the
[HTTP basic authentication header](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side)
that provides the web service with your credentials.

For the following examples, replace `{account_id}` and `{license_key}`
(including the brackets) with your
[account ID and license key](https://www.maxmind.com/en/accounts/current/license-key),
and replace `{ip_address}` with the IP address you wish to look up.

#### GeoIP Country

```bash
# Retrieve data for your IP address.
curl -u "{account_id}:{license_key}" \
  "https://geoip.maxmind.com/geoip/v2.1/country/me?pretty"

# Retrieve data for an arbitrary IP address.
curl -u "{account_id}:{license_key}" \
  "https://geoip.maxmind.com/geoip/v2.1/country/{ip_address}?pretty"
```

#### GeoIP City Plus

```bash
# Retrieve data for your IP address.
curl -u "{account_id}:{license_key}" \
  "https://geoip.maxmind.com/geoip/v2.1/city/me?pretty"

# Retrieve data for an arbitrary IP address.
curl -u "{account_id}:{license_key}" \
  "https://geoip.maxmind.com/geoip/v2.1/city/{ip_address}?pretty"
```

#### GeoIP Insights

```bash
# Retrieve data for your IP address.
curl -u "{account_id}:{license_key}" \
  "https://geoip.maxmind.com/geoip/v2.1/insights/me?pretty"

# Retrieve data for an arbitrary IP address.
curl -u "{account_id}:{license_key}" \
  "https://geoip.maxmind.com/geoip/v2.1/insights/{ip_address}?pretty"
```

#### GeoLite Country

```bash
# Retrieve data for your IP address.
curl -u "{account_id}:{license_key}" \
  "https://geolite.info/geoip/v2.1/country/me?pretty"

# Retrieve data for an arbitrary IP address.
curl -u "{account_id}:{license_key}" \
  "https://geolite.info/geoip/v2.1/country/{ip_address}?pretty"
```

#### GeoLite City

```bash
# Retrieve data for your IP address.
curl -u "{account_id}:{license_key}" \
  "https://geolite.info/geoip/v2.1/city/me?pretty"

# Retrieve data for an arbitrary IP address.
curl -u "{account_id}:{license_key}" \
  "https://geolite.info/geoip/v2.1/city/{ip_address}?pretty"
```