CorrectMe API_v.1.2.0

CorrectMe API

v. 1.2.0

Оглавление

1. Общие сведения ....................................................................................................................................... 3

1.1. Авторизация ...................................................................................................................................... 3

1.2. Структура ответа ............................................................................................................................... 3

1.3. Коды ошибок сервиса ...................................................................................................................... 4

2. История изменений .................................................................................................................................. 5

3. API............................................................................................................................................................... 6

3.1. Correct Name API ............................................................................................................................... 6

3.2. Correct ThirdName API ....................................................................................................................... 7

3.3. Correct SurName API .......................................................................................................................... 7

3.4. Correct FullName API ......................................................................................................................... 8

3.5. Suggest Name API............................................................................................................................... 9

3.6. Suggest ThirdName API .................................................................................................................... 10

3.7. Suggest SurName API ....................................................................................................................... 11

3.8. Suggest FullName API ....................................................................................................................... 12

3.9. Generate ThirdName API ................................................................................................................. 14

3.10. Correct Address API ...................................................................................................................... 15

3.11. Suggest Address API ..................................................................................................................... 16

3.12. Get LegalInfo API .......................................................................................................................... 22

2

1. Общие сведения

API позволяет клиентами интегрировать функционал CorrectMe в свои программные комплексы.

Для передачи данных используется защищенный протокол передачи данных HTTPS. При отправке

запросов значения параметров должны быть преобразованы в US-ASCII, для тестирования можно

воспользоваться онлайн сервисом https://www.urlencoder.org/, браузеры умеют автоматически

конвертировать значения параметров в US-ASCII формат.

Все API могут возвращать ответ в формате JSON или XML.

Адрес сайта: https://correctme.com.ua

1.1. Авторизация

Для осуществления запросов необходимо получить электронный ключ доступа – etoken, и потом

передавать его в заголовке (header) или в строке запроса.

Пример: получить имена, которые начинаются на «Ант», для этого данное значение должно

быть перекодировано (для примера можно использовать https://www.urlencoder.org/),

перекодированное значение - %D0%90%D0%9D%D0%A2

- через header:

curl –i -H "etoken: {etoken}"

"https://correctme.com.ua/api/v1/suggestName?name=%D0%90%D0%9D%D0%A2"

- через параметры запроса:

curl –i

"https://correctme.com.ua/api/v1/suggestName?name=%D0%90%D0%9D%D0%A2&etoken={eto

ken}"

, где {etoken} – полученное значение электронного ключа.

1.2. Структура ответа

Каждый ответ содержит три элемента:

- request – информация о запросе, присвоенный ID запроса, параметры;

- error – информация об ошибке (если запрос выполнен без ошибок, то значение будет null);

- response – ответ от API.

Также в ответе заполняются три заголовка (header):

- Response-Status – статус обработки запроса (может быть - SUCCESS либо FAILURE);

- Error-Message – сообщение об ошибке, опциональный, только если Response-Status: FAILURE;

- Error-Code – код ошибки, опциональный, только если Response-Status: FAILURE.

3

1.3. Коды ошибок сервиса

Данные коды можно увидеть в элементе ответа “error” а также в заголовке “Error-Code”.

Код Описание HTTP

status

0001 Некорректное значение etoken 200

0002 Не задан параметр etoken 200

0003 Не задан обязательный параметр 200

0004 Значение для параметра не задано 200

0005 Запрашиваемый URL не найден 404

0006 Задано некорректное значение для параметра запроса 200

0007 Account-сервис недоступен 500

0008 Период действия etoken истек 200

0010 Search-сервис временно не готов к обслуживанию запросов 500

0011 Внутренняя ошибка Search-сервиса 500

0012 Поиск с «-» (дефис) не поддерживается для запрашиваемого API 200

0013 Слишком много значений разделенных «-» (дефис) 200

0014 Задано слишком мало символов для поиска 200

0015 Версия API не поддерживается 200

0100 Сервис недоступен 503

0500 Сервис еще не готов (запускается) 503

0501 Сервис выполняет перезагрузку 503

4

2. История изменений

Версия

Описание изменений

1.0.0 Начальная версия

1.1.0 Добавлена поддержка польского (pl) языка для следующих API: SuggestName,

SuggestSurname, CorrectName, CorrectSurname

1.2.0 Добавлена информация по SuggestAddress API

5

3. API

Список доступных API:

1. GET /api/v1/correctName

2. GET /api/v1/correctThirdName

3. GET /api/v1/correctSurName

4. GET /api/v1/correctFullName

5. GET /api/v1/suggetName

6. GET /api/v1/suggestThirdName

7. GET /api/v1/suggestSurName

8. GET /api/v1/suggestFullName

9. GET /api/v1/generateThirdName

10. GET /api/v1/correctAddress

11. GET /api/v1/suggestAddress

12. GET /api/v1/getLegalInfo

3.1. Correct Name API

Позволяет исправить ошибку в имени.

URL: /api/v1/correctName

Метод: GET

Параметры:

Параметр Тип Обязательный Описание Пример

name varchar(128) Да Имя для исправления Алексей

etoken varchar(32) Да Электронный ключ 123

gender varchar(10) Нет Пол.

male

Допустимые значения: male, female

locale varchar(2) Нет Язык ответа.

ua

Допустимые значения: ua, ru, pl.

По умолчанию: ua

rf varchar(10) Нет Формат ответа.

Допустимые значения: xml, json.

Значение по умолчанию: json

Пример запроса: https://correctme.com.ua/api/v1/correctName?name=Алексей&etoken=123

Пример ответа:

{

"request": {

"requestId":"4",

"name":"Алексей",

"gender":null,

"locale":"UA",

6

}

"version":"v1"

},

"error":null,

"response": {

"name":"Олексій"

}

3.2. Correct ThirdName API

Исправление ошибок в отчестве.

URL: /api/v1/correctThirdName

Метод: GET

Параметры:


name varchar(128) Да Отчество для исправления Вытальович



male



ua

Допустимые значения: ua, ru.





Пример запроса:

https://correctme.com.ua/api/v1/correctThirdName?name=Вытальович&etoken=123124142


{

}

"request": {

"requestId":"5",

"thirdName":"Вытальович",

"gender":null,

"locale":"UA",

"version":"v1"

},

"error":null,

"response": {

"name":"Віталійович"

}

3.3. Correct SurName API

7

Исправление ошибок в фамилии.

URL: /api/v1/correctSurName

Метод: GET

Параметры:


name varchar(128) Да Фамилия для исправления Маколаенко



male



ua






Пример запроса: https://correctme.com.ua/api/v1/correctSurName?name=Маколаенко&etoken=12222


{

}

"request": {

"requestId": "7",

"surName": "Маколаенко",

"gender": null,

"locale": "UA",

"version":"v1"

},

"error": null,

"response": {

"name": "Миколаенко"

}

3.4. Correct FullName API

Позволяет исправить ошибки в ФИО.

URL: /api/v1/correctFullName

Метод: GET

Параметры:


fullname varchar(256) Да ФИО для исправления Маколаєнко

Атон Петровч

inPattern varchar(3) Да Шаблон входящего значения. SNT

Допустимые значения: S - фамилия,

N - имя, T - отчество


8

outPattern varchar(3) Нет Шаблон результатов.

Допустимые значения: S - фамилия,

N - имя, T – отчество.

Если значение не задано, то будет

использовано значение из

параметра [inPattern]









male

ua

Пример запроса: https://correctme.com.ua/api/v1/correctFullName?fullname=Маколаєнко Атон

Петровч&inPattern=SNT&etoken=123


{

}

"request": {

"requestId": "20180424132359_3",

"fullName": "Маколаєнко Атон Петровч",

"inPattern": "SNT",

"outPattern": null,

"gender": null,

"locale": "UA",

"version": "v1"

},

"error": null,

"response": {

"correctFullName": "Миколаєнко Антон Петрович",

"name": "Антон",

"surName": "Миколаєнко",

"thirdName": "Петрович"

}

3.5. Suggest Name API

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

возможных ошибок (например: введение имени на русском языке для украинского варианта).

Значения отсортированы в порядке уменьшения популярности имени.

URL: /api/v1/suggestName

Метод: GET

Параметры:


name varchar(64) Да Первые буквы имени. Вал

9

Минимум 3 символа.


fuzzy varchar(10) Нет Включает поиск с учетом ошибок. true

Допустимые значения: true, false.

Значение по умолчанию: true


ua






Пример запроса: https://correctme.com.ua/api/v1/suggestName?name=Вал&etoken=123


{

"request": {

"requestId": "20180110215241_3",

"name": "Вал",

"locale": "UA",

"version": "v1"

},

"error": null,

"response": {

"values": [

"Валерій",

"Валерія",

"Валентин",

"Валентина"

]

}

}

3.6. Suggest ThirdName API

Возвращает первые 10 отчеств по начальным буквам отчества с учетом возможных ошибок.

Значения отсортированы в порядке уменьшения популярности отчества.

URL: /api/v1/suggestThirdName

Метод: GET

Параметры:


name varchar(64) Да Первые буквы отчества для поиска. Вал








ua

10





Пример запроса: https://correctme.com.ua/api/v1/suggestThirdName?name=Вал&etoken=123


{

}

"request": {

"requestId": "20180110215241_3",

"name": "Вал",

"locale": "UA",

"fuzzy": false,

"version": "v1"

},

"error": null,

"response": {

"values": [

"Валеріївна",

"Валерійович",

"Валентинівна",

"Валентинович",

"Валер’янівна",

"Валеріанівна",

"Валер’янович",

"Валеріанович",

"Вальтерович",

"Вальтерівна",

"Вальдемарівна",

"Вальдемарович",

"Валеріянович"

]

}

3.7. Suggest SurName API

Возвращает первые 10 фамилия по начальным буквам отчества с учетом возможных ошибок.

Значения отсортированы в порядке уменьшения популярности фамилии.

URL: /api/v1/suggestSurName

Метод: GET

Параметры:


name varchar(64) Да Первые буквы фамилии для поиска. Вал


11






ua






Пример запроса: https://correctme.com.ua/api/v1/suggestSurName?name=Вал&etoken=123


{

"request": {

"requestId": "20180110215241_3",

"name": "Вал",

"locale": "UA",

"fuzzy": false,

"version": "v1"

},

"error": null,

"response": {

"values": [

"Вальчук",

"Валько",

"Валюх",

"Валігура",

"Валова",

"Валькова",

"Валах",

"Вальков",

"Валуйська",

"Валуєв",

"Валєєва",

"Валовий",

"Валуєва",

"Валуйський",

"Валєєв"

]

}

}

3.8. Suggest FullName API

Возвращает список возможных значений для полного ФИО по заданному начальному значению с

учетом возможных ошибок (введение на английской раскладке).

Входное значение делится на составляющие части, которые разделены пробелом, сначала

определяется тип для первого слова (фамилия, имя или отчество), следующее слово выбирается из

12

недостающих типов - например, если первое слово было определено как фамилия, то следующее

слово может быть либо именем, либо отчеством.

Значения отсортированы в порядке уменьшения популярности.

URL: /api/v1/suggestFullName

Метод: GET

Параметры:


name varchar(256) Да Первые буквы ФИО для поиска. Антон%20Gtnh







ua






Пример запроса: https://correctme.com.ua/api/v1/suggestFullName?name=Антон%20Gtnh&etoken=123


{

"request": {

"requestId": "20180902085959_2",

"name": "Антон Gtnh",

"locale": "UA",

"fuzzy": false,

"version": "v1"

},

"error": null,

"response": {

"values": [

{


"surName": null,

"thirdName": "Петрович",

"gender": "male"

},

{


"surName": "Петраш",

"thirdName": null,

"gender": "male"

},

{

13


"surName": "Петрик",

"thirdName": null,

"gender": "male"

},

{


"surName": "Петрук",

"thirdName": null,

"gender": "male"

},

{


"surName": "Петренко",

"thirdName": null,

"gender": "male"

}

]

}

}

3.9. Generate ThirdName API

Возвращает отчество для входящего значения имени (ошибки в имени будут исправлены).

Если не задавать пол для отчества, то сервис вернет список отчеств (мужское и женское).

URL: /api/v1/generateThirdName

Метод: GET

Параметры:


name varchar(128) Да Имя.

Володимр




Допустимые значения: male,

female


ua







https://correctme.com.ua/api/v1/generateThirdName?name=Володимр&etoken=123&gender=male


{

"request": {

"requestId": "20180126002317_1",

14

}

"name": "Володимр",

"gender": "male",

"fuzzy": false

},

"error": null,

"response": {

"name":"Володимир",

"thirdNames": [ {

"thirdName": "Володимирович",

"gender": "MALE"

}]

}

3.10. Correct Address API

Возвращает нормализованный полный адрес по заданному значению адреса.

Для осуществления поиска должны быть указаны минимум 3 составляющих адреса, которые

разделены разделителем (по умолчания запятая).

URL: /api/v1/correctAddress

Метод: GET

Параметры:


address varchar(512) Да Строка адреса для поиска в

произвольной форме с

разделителями.

Разделитель по умолчанию: «,»

Киев, бульв.

Држби нардів,

б.38


delimiter varchar(1) Нет Разделитель.

Значение по умолчанию: «,»


Допустимые значения: ua.





ua


https://correctme.com.ua/api/v1/correctAddress?address=Киев,бульв.Држби

нардів,б.38&delimiter=,&etoken=123


{

"request": {

"requestId": "86_20190814203205_634076",

"address": " Киев,бульв.Држби нардів,б.38",

15

"delimiter": ",",

"numFilter": true,

"debug": false,

"locale": "UA",

"version": "v1"

},

"error": null,

"response": {

"area": "Київ",

"region": null,

"localityType": "м.",

"locality": "Київ",

"streetType": "бульв.",

"street": "Дружби Народів",

"streetNumber": "38",

"flatNumber": null,

"postCode": "01014"

}

}

3.11. Suggest Address API

Возвращает список возможных значений (первые 10 записей) для адреса по заданному начальному

значению с учетом возможных ошибок или старых названий (населенного пункта, улицы). Входное

значение делится на составляющие части, которые разделены запятой: первый аргумент - название

населённого пункта с префиксом, указующим его тип (город, пгт, село); второй аргумент - название

улицы с префиксом, указующим его тип (переулок, проспект и т.д.); третий аргумент - номер дома.

Ввод адреса производится постепенным уточнением, начиная от населённого пункта, и заканчивая

номером дома.

Значения населённых пунктов и улиц отсортированы в порядке уменьшения их значимости.

URL: /api/v1/suggestAddress

Метод: GET

Параметры:


address varchar(512) Да Строка запроса Киев



ua

Допустимые значения: ua.





Пример рабочей сессии:

Конечный пользователь вводит последовательность выбора:

16

К

м. Київ,

м. Київ, просп. Перемоги,

м. Київ, просп. Перемоги, 1

м. Київ, просп. Перемоги, 16

Пример запроса (первый):

https://correctme.com.ua/api/v1/suggestAddress?address=к&etoken=123


{

"request": {

"requestId": "17_20191121171619_69055",

"address": "к",

"locale": "UA",

"version": "v1"

},

"error": null,

"response": {

"values": [

{

"suggestion": "м. київ, ",

"area": null,

"region": null,

"city": "м. київ",

"street": null,

"number": null

},

{

"suggestion": "м. кривий ріг, ",

"area": "дніпропетровська обл.",

"region": null,

"city": "м. кривий ріг",

"street": null,

"number": null

},

{

"suggestion": "м. кропивницький(кіровоград), ",

"area": "кіровоградська обл.",

"region": null,

"city": "м. кропивницький(кіровоград)",

"street": null,

"number": null

},

{

"suggestion": "м. кам’янське(дніпродзержинськ), ",

"area": "дніпропетровська обл.",

"region": null,

"city": "м. кам’янське(дніпродзержинськ)",

"street": null,

"number": null

},

17

{

"suggestion": "м. хрустальний(красний луч), ",

"area": "луганська обл.",

"region": null,

"city": "м. хрустальний(красний луч)",

"street": null,

"number": null

},

{

"suggestion": "м. конотоп, ",

"area": "сумська обл.",

"region": " конотопський р-н",

"city": "м. конотоп",

"street": null,

"number": null

}

]

}

}

Пример запроса (подсказка по улицам)

https://correctme.com.ua/api/v1/suggestAddress?address=м. київ,&etoken=123

{

"request": {

"requestId": "17_20191121171747_69117",

"address": "м. київ,",

"locale": "UA",

"version": "v1"

},

"error": null,

"response": {

"values": [

{

"suggestion": "м. київ, просп. перемоги, ",

"area": null,

"region": null,


"street": "просп. перемоги",

"number": null

},

{

"suggestion": "м. київ, вул. бальзака оноре де, ",

"area": null,

"region": null,


"street": "вул. бальзака оноре де",

"number": null

},

{

"suggestion": "м. київ, просп. маяковського володимира, ",

"area": null,

"region": null,

18


"street": "просп. маяковського володимира",

"number": null

},

{

"suggestion": "м. київ, просп. комарова космонавта, ",

"area": null,

"region": null,


"street": "просп. комарова космонавта",

"number": null

},

{

"suggestion": "м. київ, просп. повітрофлотський, ",

"area": null,

"region": null,


"street": "просп. повітрофлотський",

"number": null

},

{

"suggestion": "м. київ, бульв. лесі українки, ",

"area": null,

"region": null,


"street": "бульв. лесі українки",

"number": null

}

]

}

}

Пример запроса (подсказка по номерам домов на улице):

https://correctme.com.ua/api/v1/suggestAddress?address=м. київ, просп. перемоги,&etoken=123

{

"request": {

"requestId": "17_20191121172004_69325",

"address": "м. київ, просп. перемоги,",

"locale": "UA",

"version": "v1"

},

"error": null,

"response": {

"values": [

{

"suggestion": "м. київ, просп. перемоги, буд. 1",

"area": null,

"region": null,



"number": "1"

},

19

{


"area": null,

"region": null,



"number": "2"

},

{

"suggestion": "м. київ, просп. перемоги, буд. 3а",

"area": null,

"region": null,



"number": "3а"

},

{


"area": null,

"region": null,



"number": "3"

},

{


"area": null,

"region": null,



"number": "4"

}

]

}

}

Пример запроса (подсказка по номерам домов, которые начинаются с «1»):

https://correctme.com.ua/api/v1/suggestAddress?address=м. київ, просп. перемоги, 1&etoken=123

{

"request": {

"requestId": "17_20191121172122_69412",

"address": "м. київ, просп. перемоги, 1",

"locale": "UA",

"version": "v1"

},

"error": null,

"response": {

"values": [

{


"area": null,

"region": null,

20



"number": "1"

},

{


"area": null,

"region": null,



"number": "10"

},

{

"suggestion": "м. київ, просп. перемоги, буд. 11а",

"area": null,

"region": null,



"number": "11а"

},

{


"area": null,

"region": null,



"number": "16"

},

{


"area": null,

"region": null,



"number": "18"

}

]

}

}

Пример подсказки с полным адресом:

https://correctme.com.ua/api/v1/suggestAddress?address=м. київ, просп. перемоги, 16&etoken=123

{

"request": {

"requestId": "17_20191121172315_69548",

"address": "м. київ, просп. перемоги, 16",

"locale": "UA",

"version": "v1"

},

"error": null,

"response": {

"values": [

21

{


"area": null,

"region": null,



"number": "16"

}

]

}

}

3.12. Get LegalInfo API

Возвращает информацию о юридическом лице по его названию или частичному названию или же по

коду.

URL: /api/v1/getLegalInfo

Метод: GET

Параметры:


q varchar(256) Да Название компании или ее код.

Минимум 2 символа





Перша

броварня

31978272


https://correctme.com.ua/api/v1/getLegalInfo?q=перша%20броварня&etoken=123

или

https://correctme.com.ua/api/v1/getLegalInfo?q=31978272&etoken=123


{

"request": {

"requestId": "20180915154653_3",

"q": "перша броварня"

},

"error": null,

"response": {

"values": [

{

"code": "31978272",

22

"name": "ТОВАРИСТВО З ОБМЕЖЕНОЮ ВІДПОВІДАЛЬНІСТЮ ТОРГОВО-ВИРОБНИЧА КОМПАНІЯ

\"ПЕРША ПРИВАТНА БРОВАРНЯ \"ДЛЯ ЛЮДЕЙ - ЯК ДЛЯ СЕБЕ!\"",

"shortName": "ТЗОВ ТВК \"ПЕРША ПРИВАТНА БРОВАРНЯ \"ДЛЯ ЛЮДЕЙ - ЯК ДЛЯ СЕБЕ!\"",

"address": "79032, Львівська обл., місто Львів, Сихівський район, ВУЛИЦЯ ДЖОРДЖА

ВАШИНГТОНА, будинок 10",

"director": "АМБАРЦУМЯН ГЕОРГІЙ АРТЕМОВИЧ",

"kved": "11.05 Виробництво пива",

"status": "зареєстровано",

"founders": [

"КОМПАНІЯ \"БОНЕТЕН ЛІМІТЕД\", розмір внеску до статутного фонду - 46720500.00 грн.",

"КІНЦЕВИЙ БЕНЕФІЦІАРНИЙ ВЛАСНИК (КОНТРОЛЕР)-ХЕНДЕРСОН-СТЮАРТ

НІКОЛАС,БЕЛЬГІЯ,М.БРЮСЕЛЬ 10 МО РІС АВЕНЮ,ІНД.1050",

"КІНЦЕВИЙ БЕНЕФІЦІАРНИЙ ВЛАСНИК (КОНТРОЛЕР) - ОТТІНГЕР БРАУРЕЙ ГМБХ,НІМЕЧЧИНА,

М.ЕТТІНГЕР,ВУЛИЦЯ БРАУХАУ-ШТРАССЕ 8,ІНД.86732",

"КІНЦЕВИЙ БЕНЕФІЦІАРНИЙ ВЛАСНИК (КОНТРОЛЕР)-ЄВРОПЕЙСЬКИЙ БАНК РЕКОНСТРУКЦІЇ ТА

РОЗВИТКУ,ВЕЛИКОБРИТАНІЯ,М.ЛОНДОН,E C2A2JN ЕКСЧЕНДЖ СКВЕАР 1",

"\"КІНЦЕВИЙ БЕНЕФІЦІАРНИЙ ВЛАСНИК (КОНТРОЛЕР) - МАЦОЛА АНДРІЙ МИКОЛАЙОВИЧ,

УКРАЇНА, ПАСПОРТ , ІНДЕКС 79010, ЛЬВІВСЬКА ОБЛ., М. ЛЬВІВ, ВУЛЛИЦЯ НЕКРАСОВА, БУД. 10, КВ.

21\""

]

}

]

}

}

23

CorrectMe API_v.1.2.0

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?