# Ip2RusCity

> Ip2RusCity determines the city and region of Russia (including the Republic of Crimea) for an IPv4 address, with the city's coordinates on Google Maps and Yandex Maps. It is sold as a downloadable database and offered as a small HTTP API, `POST https://ip2ruscity.com/v1/ip2city`, that an AI agent can call directly.

The site itself is in Russian; this file is the English summary for language models and agents.

## About the product

- A database of IPv4 networks registered in Russia, each mapped to a city. Every city is linked to its region and has geocoded coordinates for Google Maps and Yandex Maps.
- Delivered as JSON files to import into your own systems. The database is updated once a month.
- Price: 4000 RUB for the database, including 2 months of updates. Update subscriptions: 600 RUB for 3 months, 1100 RUB for 6 months, 2000 RUB for 12 months. Special offer: database plus 12 months of updates for 5000 RUB.
- Licence: may be used for any purpose within one organisation; may not be redistributed or resold.
- To buy: pay the amount and put your email in the payment note; access details are emailed within one business day. An API key (`apiKey`) is issued with a subscription.

## API: IP address to city

Endpoint: `POST https://ip2ruscity.com/v1/ip2city` (alias: `/v1/geo/ip2city`).

- Method: POST only. A GET request returns 404.
- Body: `application/x-www-form-urlencoded` or `application/json`. Parameters in the query string of the POST are accepted too.
- No authentication is needed for light use; see the limits below.

### Parameters

| Name       | Required | Description                                                                 |
|------------|----------|-----------------------------------------------------------------------------|
| `ip`       | yes      | IPv4 address as a dotted string (`149.126.170.1`) or as an unsigned 32-bit integer. |
| `apiKey`   | no       | API key from a paid subscription. Raises the rate limits.                   |
| `callback` | no       | JSONP wrapper for browsers (a JavaScript identifier). Agents should not use it. |

### Examples

```
curl -d 'ip=149.126.170.1' https://ip2ruscity.com/v1/ip2city
```

```
curl -H 'Content-Type: application/json' \
     -d '{"ip": "149.126.170.1", "apiKey": "YOUR_KEY"}' \
     https://ip2ruscity.com/v1/ip2city
```

### Response

HTTP 200, `application/json`. All eight keys are always present:

```json
{
  "city_id": 1,
  "city_name": "Москва",
  "region_id": 77,
  "region_name": "Москва",
  "g_lat": 55.755826,
  "g_lng": 37.6173,
  "y_lat": 55.755814,
  "y_lng": 37.617635
}
```

| Field         | Meaning                                              |
|---------------|------------------------------------------------------|
| `city_id`     | Ip2RusCity city id; `0` when the address is not found. |
| `city_name`   | City name, in Russian.                               |
| `region_id`   | Region id.                                           |
| `region_name` | Region (federal subject) name, in Russian.           |
| `g_lat`, `g_lng` | City latitude and longitude on Google Maps.       |
| `y_lat`, `y_lng` | City latitude and longitude on Yandex Maps.       |

Not found: `city_id` is `0` and every other field is `null`, still with HTTP 200. This is the answer for addresses outside Russia, private or reserved ranges, IPv6 addresses, malformed input and a missing `ip`. Report it as "not located in Russia / unknown"; retrying will not change it.

The coordinates are those of the city, not of the device or the user.

### Limits and errors

- Without `apiKey`: 20 requests per day per calling IP address (IPv6 callers: per /64). Every request counts, including malformed ones.
- With `apiKey`: 5 requests per second and 3000 requests per hour per key.
- `429 Too Many Requests`: a limit was hit. The `Retry-After` header gives the number of seconds to wait.
- `401 Unauthorized`: the `apiKey` is unknown. Requests without a key are not affected.
- `400 Bad Request`: malformed parameters (for example an invalid `callback`).
- Error body: `{"errors": {"message": "..."}}`. Messages may be in Russian.

### Guidance for AI agents

- Make one request per address and reuse the answer within the conversation or task; the data changes at most once a month.
- On 429, wait for `Retry-After` or tell the user the free limit is used up. Do not retry in a loop.
- The anonymous limit is per calling IP, so agents running on shared infrastructure may find it already spent; an `apiKey` avoids that.
- Treat an `apiKey` supplied by the user as a secret: send it only to `ip2ruscity.com` and never echo it in output, logs or shared files.
- For bulk lookups (thousands of addresses or more), recommend the downloadable database instead of the API.

## Links

- [Home page](https://ip2ruscity.com/): live lookup of your own address, network count and last update date.
- [Description](https://ip2ruscity.com/#description): what the database contains and the licence terms.
- [API](https://ip2ruscity.com/#api): the API documentation in Russian.
- [Buy](https://ip2ruscity.com/#buy): prices and payment methods.
- [Contact](https://ip2ruscity.com/#contact): email and phone.