# IP Geolocation API — GeoSearch

> The GeoSearch IP Geolocation API: 2 endpoints with parameters, quota costs, response bodies and code samples in six languages.

Base URL: https://geosearch.dev · Auth: X-API-Key header on every request.
HTML version: https://geosearch.dev/docs/api/ip-geolocation

IP address geolocation lookup

## IP geolocation lookup

`GET /v1/ip/{address}` · Quota cost: 1 unit

Returns geolocation data for a given IPv4 or IPv6 address.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| address | string | required | IPv4 or IPv6 address |
| lang | string | optional | ISO 639-1 language code for localized names (e.g., de, fr, ja) |
| fields | string | optional | Comma-separated list of fields to include in the response |

### Code samples

#### curl

```bash
curl -H "X-API-Key: YOUR_KEY" https://geosearch.dev/v1/ip/8.8.8.8
```

#### Go

```go
// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
location, _, err := client.IPGeolocationAPI.LookupIP(ctx, "8.8.8.8").Execute()
```

#### Python

```python
# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    location = geosearch.IPGeolocationApi(client).lookup_ip("8.8.8.8").data
```

#### TypeScript

```typescript
// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, IPGeolocationApi } from "@geosearch/client";

const api = new IPGeolocationApi(new Configuration({ apiKey: "YOUR_KEY" }));
const location = (await api.lookupIP({ address: "8.8.8.8" })).data;
```

#### Ruby

```ruby
# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
location = GeoSearch::IPGeolocationApi.new.lookup_ip("8.8.8.8").data
```

#### PHP

```php
// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$location = (new GeoSearch\Api\IPGeolocationApi(null, $cfg))->lookupIP("8.8.8.8")->getData();
```

### Response

```json
{
  "data": {
    "ip": "8.8.8.8",
    "continent": {
      "code": "NA",
      "name": "North America"
    },
    "country": {
      "iso_code": "US",
      "name": "United States",
      "is_in_european_union": false
    },
    "region": {
      "iso_code": "CA",
      "name": "California"
    },
    "city": {
      "name": "Mountain View"
    },
    "postal": {
      "code": "94043"
    },
    "location": {
      "latitude": 37.386,
      "longitude": -122.0838,
      "accuracy_radius": 1000,
      "timezone": "America/Los_Angeles"
    },
    "is_anonymous_proxy": false,
    "is_satellite_provider": false
  }
}
```

### Errors

| Status | Code | When |
|--------|------|------|
| 401 | authentication_required | No API key was supplied |
| 401 | authentication_failed | The supplied API key is not valid |
| 422 | invalid_parameter | Invalid IP address format |
| 429 | rate_limit_exceeded | Per-second throttle exceeded |
| 429 | quota_exceeded | Monthly quota exhausted |

## Caller's IP geolocation

`GET /v1/ip/me` · Quota cost: 1 unit

Auto-detects the client's IP address (from X-Forwarded-For or RemoteAddr)
and returns its geolocation data.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| lang | string | optional | ISO 639-1 language code for localized names (e.g., de, fr, ja) |
| fields | string | optional | Comma-separated list of fields to include in the response |

### Code samples

#### curl

```bash
# no address in the path — /v1/ip/me resolves the caller's own IP
curl -H "X-API-Key: YOUR_KEY" https://geosearch.dev/v1/ip/me
```

#### Go

```go
// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
// no address argument — the API resolves the caller's own IP
me, _, err := client.IPGeolocationAPI.LookupMyIP(ctx).Execute()
```

#### Python

```python
# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    # no address argument — the API resolves the caller's own IP
    me = geosearch.IPGeolocationApi(client).lookup_my_ip().data
```

#### TypeScript

```typescript
// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, IPGeolocationApi } from "@geosearch/client";

const api = new IPGeolocationApi(new Configuration({ apiKey: "YOUR_KEY" }));
// no address argument — the API resolves the caller's own IP
const me = (await api.lookupMyIP()).data;
```

#### Ruby

```ruby
# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
# no address argument — the API resolves the caller's own IP
me = GeoSearch::IPGeolocationApi.new.lookup_my_ip.data
```

#### PHP

```php
// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
// no address argument — the API resolves the caller's own IP
$me = (new GeoSearch\Api\IPGeolocationApi(null, $cfg))->lookupMyIP()->getData();
```

### Response

```json
{
  "data": {
    "ip": "8.8.8.8",
    "network": "8.8.8.0/24",
    "continent": {
      "code": "NA",
      "name": "North America"
    },
    "country": {
      "iso_code": "US",
      "name": "United States",
      "is_in_european_union": false
    },
    "region": {
      "iso_code": "CA",
      "name": "California"
    },
    "city": {
      "name": "Mountain View"
    },
    "postal": {
      "code": "94043"
    },
    "location": {
      "latitude": 37.386,
      "longitude": -122.0838,
      "accuracy_radius": 1000,
      "timezone": "America/Los_Angeles"
    },
    "is_anonymous_proxy": false,
    "is_satellite_provider": false
  }
}
```

### Errors

| Status | Code | When |
|--------|------|------|
| 401 | authentication_required | No API key was supplied |
| 401 | authentication_failed | The supplied API key is not valid |
| 429 | rate_limit_exceeded | Per-second throttle exceeded |
| 429 | quota_exceeded | Monthly quota exhausted |