IP Geolocation API

Parameters

Code samples

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

// 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()

# 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

// 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;

# 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

// 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

{
  "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

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

422 invalid_parameter

{
  "error": {
    "code": "invalid_parameter",
    "message": "invalid IP address format",
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}

Parameters

Code samples

# 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 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()

# 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

// 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;

# 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

// 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

{
  "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

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}