# HumanData API — Machine-Readable Documentation

> Base URL: https://api.humandata.ru
> Auth: Header `Authorization: Token YOUR_API_KEY`
> Format: JSON
> Charset: UTF-8

## Endpoints

### POST /api/v1/clean/name
Standardize a Russian full name (FIO). Returns parsed surname, name, patronymic, gender.

Request:
```json
{"query": "иванов сергей петрович"}
```

Response:
```json
{
  "source": "иванов сергей петрович",
  "result": {
    "surname": "Иванов",
    "name": "Сергей",
    "patronymic": "Петрович",
    "gender": "m",
    "qc": 0
  }
}
```

Fields:
- surname (string|null) — Last name
- name (string|null) — First name
- patronymic (string|null) — Patronymic
- gender (string|null) — "m" or "f"
- qc (int) — Quality: 0=found in dictionary, 1=incomplete, 2=not found

### POST /api/v1/clean/address
Standardize a Russian address. Returns parsed components, FIAS ID, and coordinates.

Request:
```json
{"query": "москва ленинский 42"}
```

Response:
```json
{
  "source": "москва ленинский 42",
  "result": {
    "result": "г Москва, пр-кт Ленинский",
    "region": "г Москва",
    "city": null,
    "street": "пр-кт Ленинский",
    "house": "42",
    "flat": null,
    "postal_code": null,
    "fias_id": "5f2a1243-a57b-418e-baee-ff76f4993b45",
    "geo_lat": 55.7034,
    "geo_lon": 37.5659,
    "qc_geo": 0,
    "qc": 0
  }
}
```

Note: Federal cities (Moscow, Saint Petersburg, Sevastopol) are returned as region with city=null.
Address components use FIAS abbreviations (г=город, пр-кт=проспект, ул=улица, д=дом).

Fields:
- result (string|null) — Full normalized address
- region (string|null) — Region (federal subject)
- city (string|null) — City or settlement
- street (string|null) — Street
- house (string|null) — House number
- flat (string|null) — Apartment
- postal_code (string|null) — Postal code
- fias_id (string|null) — FIAS registry UUID
- geo_lat (float|null) — Latitude (WGS-84)
- geo_lon (float|null) — Longitude (WGS-84)
- qc_geo (int|null) — Geocoding quality: 0=house, 2=street, 3=city, 4=not found, null=disabled
- qc (int) — Address quality: 0=found in FIAS, 1=not found, 2=incomplete, 3=low confidence

### POST /api/v1/suggest/fio
Autocomplete for Russian names. Returns up to `count` suggestions.

Request:
```json
{"query": "ива", "count": 5}
```

Optional fields:
- parts (array) — Filter by part: ["NAME"], ["SURNAME"], ["PATRONYMIC"]
- count (int, 1-100, default 10) — Max suggestions

Response:
```json
{
  "suggestions": [
    {
      "value": "Иванов",
      "unrestricted_value": "Иванов",
      "data": {"gender": "m", "part": "SURNAME"}
    }
  ]
}
```

### POST /api/v1/suggest/address
Autocomplete for Russian addresses. Returns up to `count` suggestions.

Request:
```json
{"query": "моск", "count": 5}
```

Optional fields:
- count (int, 1-100, default 10) — Max suggestions
- from_bound (object) — Filter by level, e.g. {"value": "city"}

Response:
```json
{
  "suggestions": [
    {
      "value": "г Москва",
      "unrestricted_value": "Россия, г Москва",
      "data": {"fias_id": "0c5b2444-70a0-4932-980c-b4dc0d3f02b5"}
    }
  ]
}
```

## Authentication

All endpoints require `Authorization: Token YOUR_API_KEY` header.

Get an API key:
1. Register at https://humandata.ru/register
2. Go to https://humandata.ru/dashboard/api-keys
3. Create a key

## Rate Limits

- 10,000 requests per day
- 20 requests per second

## Error Responses

HTTP 401:
```json
{"detail": "Authorization header required"}
```

HTTP 422:
```json
{"detail": [{"msg": "field required", "type": "value_error.missing"}]}
```

HTTP 429:
```json
{"detail": "Daily rate limit exceeded (10000 requests/day)"}
```

## Notes

- API is compatible with DaData format for clean and suggest endpoints
- Addresses are validated against the Russian Federal Address Registry (FIAS/GAR)
- Geocoding uses OpenStreetMap data via Nominatim
- Input accepts Cyrillic, Latin transliteration, and mixed scripts
- Empty or unrecognizable input returns null fields, never hallucinates