Response Format

The proxy returns the raw JSON response from MaxMind without modification. The exact fields present depend on which MaxMind endpoint is configured (maxmind_url) and on MaxMind's coverage for the queried IP.

---

City endpoint (default)

The default maxmind_url points to the GeoIP2 City web service. A typical successful response looks like:

{
  "city": {
    "geoname_id": 5375480,
    "names": {
      "de": "Mountain View",
      "en": "Mountain View",
      "fr": "Mountain View",
      "ja": "マウンテンビュー",
      "zh-CN": "芒廷维尤"
    }
  },
  "continent": {
    "code": "NA",
    "geoname_id": 6255149,
    "names": { "en": "North America" }
  },
  "country": {
    "geoname_id": 6252001,
    "iso_code": "US",
    "names": { "en": "United States" }
  },
  "location": {
    "accuracy_radius": 1000,
    "latitude": 37.386,
    "longitude": -122.0838,
    "metro_code": 807,
    "time_zone": "America/Los_Angeles"
  },
  "postal": {
    "code": "94035"
  },
  "registered_country": {
    "geoname_id": 6252001,
    "iso_code": "US",
    "names": { "en": "United States" }
  },
  "subdivisions": [
    {
      "geoname_id": 5332921,
      "iso_code": "CA",
      "names": { "en": "California" }
    }
  ],
  "traits": {
    "ip_address": "8.8.8.8",
    "network": "8.8.8.0/24"
  }
}

Key fields

Field	Description
city.names.en	City name in English (and other languages where available).
country.iso_code	Two-letter ISO 3166-1 country code.
country.names.en	Country name in English.
location.latitude / location.longitude	Approximate coordinates.
location.accuracy_radius	Radius in kilometres within which the IP is located (approximate).
location.time_zone	IANA time zone identifier (e.g. America/Los_Angeles).
postal.code	Postal/ZIP code where available.
subdivisions[0].iso_code	State, province, or region code.
traits.ip_address	The queried IP address as echoed by MaxMind.
traits.network	The CIDR block the IP belongs to.

---

Country endpoint

If maxmind_url is set to the Country endpoint, the city, postal, and subdivisions fields are absent. The response is smaller and cheaper to store in Redis.

---

MaxMind error responses

When MaxMind cannot resolve the IP or the request is invalid, the response body contains an "error" field:

{
  "code": "IP_ADDRESS_NOT_FOUND",
  "error": "The supplied IP address is not in the database."
}

Common MaxMind error codes:

Code	Meaning
IP_ADDRESS_NOT_FOUND	MaxMind has no data for this IP.
IP_ADDRESS_RESERVED	The IP is a private or reserved address (RFC 1918, loopback, etc.).
ACCOUNT_ID_REQUIRED	maxmind_username is missing or empty.
LICENSE_KEY_REQUIRED	maxmind_password is missing or empty.
AUTHORIZATION_INVALID	Username or password is incorrect.
OUT_OF_QUERIES	Your MaxMind query quota is exhausted.

For the full list see the MaxMind API documentation.