> For the complete documentation index, see [llms.txt](https://docs.k9.io/key9-identity/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.k9.io/key9-identity/maxmind-api-proxy/api-reference/response-format.md).

# 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:

```json
{
  "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:

```json
{
  "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](https://dev.maxmind.com/geoip/docs/web-services/responses#errors).