> 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).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.k9.io/key9-identity/maxmind-api-proxy/api-reference/response-format.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.