Навигация

API Документация

Обзор

Normatico API предоставляет мощный инструментарий для интеллектуальной обработки имён: нормализация, перевод, определение пола и извлечение из email адресов.

Базовый URL: https://api.normatico.com/v1

Аутентификация

Все запросы к API должны содержать API ключ в заголовке:

X-API-Key: your-api-key-here
Получение API ключа
  1. Зарегистрируйтесь на сайте
  2. Перейдите в личный кабинет
  3. Создайте новый API ключ

Методы API

Метод Endpoint Описание
POST /normalize Нормализация имени
POST /translate Перевод имени
POST /gender Определение пола
POST /extract-from-email Извлечение из email
POST /batch Batch обработка
GET /languages Список поддерживаемых языков
GET /stats Статистика использования
POST /regenerate Регенерация с коррекцией

Нормализация имён

Преобразует имя в правильную форму на целевом языке.

POST /v1/normalize
Параметры запроса:
Параметр Тип Обязательный Описание
name string Да Имя для нормализации
source_language string Нет Исходный язык (auto по умолчанию)
target_language string Да Целевой язык (любой ISO 639-1 код)
style string Нет Стиль: formal, casual, media
Пример запроса:
{
  "name": "John Smith",
  "source_language": "en",
  "target_language": "ru",
  "style": "formal"
}
Пример ответа:
{
  "normalized": "Джон Смит",
  "first_name": "Джон",
  "last_name": "Смит",
  "middle_name": null,
  "gender": "male",
  "confidence": 95,
  "detected_language": "en",
  "cache_hit": false
}

Перевод имён

Переводит имя с одного языка на другой с сохранением культурного контекста.

POST /v1/translate
Параметры запроса:
Параметр Тип Обязательный Описание
name string Да Имя для перевода
from_language string Да Исходный язык
to_language string Да Целевой язык

Определение пола

Определяет пол по имени с указанием уровня уверенности.

POST /v1/gender
Пример ответа:
{
  "name": "Мария",
  "gender": "female",
  "confidence": 98,
  "alternative_genders": []
}

Извлечение из email

Извлекает и нормализует имя из email адреса.

POST /v1/extract-from-email
Пример запроса:
{
  "email": "ivan.petrov@company.com",
  "target_language": "ru"
}
Пример ответа:
{
  "email": "ivan.petrov@company.com",
  "extracted_name": "Иван Петров",
  "first_name": "Иван",
  "last_name": "Петров",
  "confidence": 90
}

Регенерация с коррекцией

Повторная обработка имени с возможностью ручной корректировки результата.

POST /v1/regenerate
Параметры запроса:
Параметр Тип Обязательный Описание
name string Да Имя для регенерации
source_language string Нет Исходный язык
target_language string Да Целевой язык
user_correction object Нет Ручная корректировка
Пример с корректировкой:
{
  "name": "მიხეილ წინამძღვრიშვილი",
  "source_language": "ka",
  "target_language": "ru",
  "user_correction": {
    "normalized": "Михеил Цинамдзгвришвили",
    "first_name": "Михеил",
    "last_name": "Цинамдзгвришвили"
  }
}

Batch обработка

Обработка множества имён за один запрос.

POST /v1/batch
Максимум 100 элементов за запрос
Пример запроса:
{
  "names": [
    {"name": "John Smith", "target_language": "ru"},
    {"name": "María García", "target_language": "en"},
    {"name": "王伟", "target_language": "ru"}
  ],
  "operation": "normalize"
}

Поддерживаемые языки

API поддерживает обработку имён на 30+ языках с детальными правилами транслитерации.

Полная поддержка (детальные правила):
  • ru - Русский
  • en - Английский
  • es - Испанский
  • fr - Французский
  • de - Немецкий
  • it - Итальянский
  • pt - Португальский
  • nl - Голландский
  • pl - Польский
  • cs - Чешский
  • sv - Шведский
  • tr - Турецкий
  • ar - Арабский
  • he - Иврит
  • hi - Хинди
  • zh - Китайский
  • ja - Японский
  • ko - Корейский
Языки бывшего СССР:
  • uk - Украинский
  • be - Белорусский
  • ka - Грузинский
  • hy - Армянский
  • az - Азербайджанский
  • kk - Казахский
  • ky - Киргизский
  • tg - Таджикский
  • uz - Узбекский
  • tk - Туркменский
Примечание: Вы можете использовать любой валидный ISO 639-1 код языка. Система автоматически обработает имя даже для языков без специальных правил.

Коды ошибок

Код Описание Решение
400 Неверный запрос Проверьте параметры запроса
401 Не авторизован Проверьте API ключ
403 Доступ запрещён Проверьте права доступа
429 Превышен лимит Подождите или обновите тариф
500 Внутренняя ошибка Обратитесь в поддержку

Лимиты использования

Free
  • 100 запросов/день
  • 10 запросов/минуту
  • Batch обработка
Pro
  • 10,000 запросов/день
  • 100 запросов/минуту
  • Batch до 50 имён
Enterprise
  • Без лимитов
  • 1000 запросов/минуту
  • Batch до 100 имён

Примеры использования

import requests

url = "https://api.normatico.com/v1/normalize"
headers = {
    "X-API-Key": "your-api-key",
    "Content-Type": "application/json"
}
data = {
    "name": "John Smith",
    "target_language": "ru"
}

response = requests.post(url, json=data, headers=headers)
result = response.json()
print(result["normalized"])  # Джон Смит
const response = await fetch('https://api.normatico.com/v1/normalize', {
    method: 'POST',
    headers: {
        'X-API-Key': 'your-api-key',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        name: 'John Smith',
        target_language: 'ru'
    })
});

const result = await response.json();
console.log(result.normalized);  // Джон Смит
curl -X POST https://api.normatico.com/v1/normalize \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "John Smith",
        "target_language": "ru"
    }'

SDK и библиотеки

Python SDK

Официальная библиотека для Python

pip install normatico
JavaScript SDK

Библиотека для Node.js и браузера

npm install normatico
Нужна помощь?

Если у вас есть вопросы или проблемы с использованием API: