Руководство разработчика по API

Документ предназначен для разработчиков, которые хотят добавить возможность поиска и использования словесных ассоциаций на свои сайты или в приложения.

Краткое содержание:

Общие сведения
JSON-интерфейс
XML-интерфейс
Коды ответов
HTTP заголовки ответа

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

Для доступа к методам API необходимо получить API-ключ, подписашись на один из доступных тарифных планов. Для того чтобы подписаться на выбранный тарифный план, а также для управления существующими подписками, пожалуйста, войдите в вашу Учётную запись API Сервиса Словесных Ассоциаций.

Для доступа к API сервиса словесных ассоциаций по HTTPS вы можете использовать:

JSON-интерфейс (ответ возвращается в формате JSON).
XML-интерфейс (ответ возвращается в виде XML-документа).

Все интерфейсы имеют одинаковую функциональность и используют одни и те же входные параметры.

JSON-интерфейс

Ответ возвращается в формате JSON.

Поддерживаются методы GET и POST.

Синтаксис запроса

https://api.wordassociations.net/associations/v1.0/json/search?
apikey=<API-ключ>
 & text=<слово или фраза>
 & lang=<язык запроса>
 & [type=<тип возвращаемого результата>]
 & [limit=<максимальное количество результатов>]
 & [pos=<искомые части речи>]
 & [indent=<включить/выключить отступы>]

apikey	API-ключ. Для получения уникального API-ключа, пожалуйста, зарегистрируйтесь и подпишитесь на один из доступных тарифных планов.
text	Слово или фраза, для которой необходимо найти ассоциации. Совет. В запросе можно использовать несколько параметров text (от 1 до 10 включительно). Таким образом, в одном ответе можно получать ассоциации для нескольких входных слов или фраз. Ограничения: Для POST-запросов максимальный размер передаваемого текста составляет 10 000 символов. В GET-запросах ограничивается не размер передаваемого текста, а размер всей строки запроса, которая кроме текста может содержать и другие параметры. Максимальный размер строки — от 2 до 10 КБ (зависит от версии используемого браузера). Размер входного текста неограничен. Однако подбор ассоциаций осуществляется лишь по первым 10 словам этого текста.
lang	Язык запроса. Задаётся в виде кода соответствующего языка. Возможные значения: en — английский; es — испанский; it — итальянский; de — немецкий; pt — португальский; ru — русский; fr — французский;
type	Тип возвращаемого результата. Возможные значения: stimulus — входными данными (параметр text) является слово-ответ. Сервис возвращает список слов-стимулов, которые чаще всего побуждают подумать о заданном слове-ответе; response — входными данными (параметр text) является слово-стимул. Сервис возвращает список ассоциативных слов-ответов, которые приходят на ум для заданного слова-стимула. Значение по умолчанию: type=stimulus
limit	Максимальное количество результатов. Позволяет ограничить количество результатов (ассоциаций) в ответе. Параметр может принимать значение от 1 до 300. Значение по умолчанию: limit=50
pos	Искомые части речи. Позволяет ограничивать результаты определёнными частями речи. Задаётся перечислением кодов частей речи, разделённых запятой. Поддерживаются следующие коды: noun — имя существительное; adjective — имя прилагательное; verb — глагол; adverb — наречие; Значение по умолчанию: pos=noun,adjective,verb,adverb
indent	Включение или выключение отступов в JSON/XML ответе. Позволяет включить или выключить пробельные отступы для ответа. Поддерживаются следующие значения: yes — включить отступы; no — выключить отступы; Значение по умолчанию: indent=yes

Примечание.Все специальные символы должны быть экранированы.

Пример запроса (GET)

GET associations/v1.0/json/search?apikey=API-KEY&text=welcome&lang=en&limit=6 HTTP/1.1
Host: api.wordassociations.net
Accept: */*

Пример запроса (POST)

POST associations/v1.0/json/search?apikey=API-KEY HTTP/1.1
Host: api.wordassociations.net
Accept: */*
Content-Length: 28
Content-Type: application/x-www-form-urlencoded

text=welcome&lang=en&limit=6

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

HTTP/1.1 200 OK
Server: nginx
Content-Type: application/json; charset=utf-8
Content-Length: 1240
Connection: keep-alive
Keep-Alive: timeout=120
Date: Mon, 04 Jul 2016 23:59:25 GMT
{
    "version": "1.0",
    "code": 200,
    "request": {
        "text": [
            "welcome"
        ],
        "lang": "en",
        "type": "stimulus",
        "limit": 6,
        "pos": "noun,adjective,verb,adverb"
    },
    "response": [
        {
            "text": "welcome",
            "items": [
                {
                    "item": "Warmly",
                    "weight": 100,
                    "pos": "adverb"
                },
                {
                    "item": "Hearty",
                    "weight": 98,
                    "pos": "adjective"
                },
                {
                    "item": "Hospitable",
                    "weight": 94,
                    "pos": "adjective"
                },
                {
                    "item": "Cordial",
                    "weight": 93,
                    "pos": "adjective"
                },
                {
                    "item": "Heartily",
                    "weight": 85,
                    "pos": "adverb"
                },
                {
                    "item": "Greet",
                    "weight": 84,
                    "pos": "verb"
                }
            ]
        }
    ]
}

XML-интерфейс

Ответ возвращается в формате XML.

Поддерживаются методы GET и POST.

Синтаксис запроса

https://api.wordassociations.net/associations/v1.0/xml/search?
apikey=<API-ключ>
 & text=<слово или фраза>
 & lang=<язык запроса>
 & [type=<тип возвращаемого результата>]
 & [limit=<максимальное количество результатов>]
 & [pos=<искомые части речи>]
 & [indent=<включить/выключить отступы>]

apikey	API-ключ. Для получения уникального API-ключа, пожалуйста, зарегистрируйтесь и подпишитесь на один из доступных тарифных планов.
text	Слово или фраза, для которой необходимо найти ассоциации. Совет. В запросе можно использовать несколько параметров text (от 1 до 10 включительно). Таким образом, в одном ответе можно получать ассоциации для нескольких входных слов или фраз. Ограничения: Для POST-запросов максимальный размер передаваемого текста составляет 10 000 символов. В GET-запросах ограничивается не размер передаваемого текста, а размер всей строки запроса, которая кроме текста может содержать и другие параметры. Максимальный размер строки — от 2 до 10 КБ (зависит от версии используемого браузера). Размер входного текста неограничен. Однако подбор ассоциаций осуществляется лишь по первым 10 словам этого текста.
lang	Язык запроса. Задаётся в виде кода соответствующего языка. Возможные значения: en — английский; es — испанский; it — итальянский; de — немецкий; pt — португальский; ru — русский; fr — французский;
type	Тип возвращаемого результата. Возможные значения: stimulus — входными данными (параметр text) является слово-ответ. Сервис возвращает список слов-стимулов, которые чаще всего побуждают подумать о заданном слове-ответе; response — входными данными (параметр text) является слово-стимул. Сервис возвращает список ассоциативных слов-ответов, которые приходят на ум для заданного слова-стимула. Значение по умолчанию: type=stimulus
limit	Максимальное количество результатов. Позволяет ограничить количество результатов (ассоциаций) в ответе. Параметр может принимать значение от 1 до 300. Значение по умолчанию: limit=50
pos	Искомые части речи. Позволяет ограничивать результаты определёнными частями речи. Задаётся перечислением кодов частей речи, разделённых запятой. Поддерживаются следующие коды: noun — имя существительное; adjective — имя прилагательное; verb — глагол; adverb — наречие; Значение по умолчанию: pos=noun,adjective,verb,adverb
indent	Включение или выключение отступов в JSON/XML ответе. Позволяет включить или выключить пробельные отступы для ответа. Поддерживаются следующие значения: yes — включить отступы; no — выключить отступы; Значение по умолчанию: indent=yes

Примечание.Все специальные символы должны быть экранированы.

Пример запроса (GET)

GET associations/v1.0/xml/search?apikey=API-KEY&text=welcome&lang=en&limit=6 HTTP/1.1
Host: api.wordassociations.net
Accept: */*

Пример запроса (POST)

POST associations/v1.0/xml/search?apikey=API-KEY HTTP/1.1
Host: api.wordassociations.net
Accept: */*
Content-Length: 28
Content-Type: application/x-www-form-urlencoded

text=welcome&lang=en&limit=6

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

HTTP/1.1 200 OK
Server: nginx
Content-Type: application/xml; charset=utf-8
Content-Length: 68
Connection: keep-alive
Keep-Alive: timeout=120
X-Content-Type-Options: nosniff
Date: Thu, 31 Mar 2016 10:50:20 GMT

<?xml version="1.0" encoding="UTF-8"?>
<wordassociationssearch version="1.0" code="200">
  <request>
    <text>welcome</text>
    <lang>en</lang>
    <type>stimulus</type>
    <limit>6</limit>
    <pos>noun,adjective,verb,adverb</pos>
  </request>
  <response>
    <results>
      <result>
        <text>welcome</text>
        <items>
          <item weight="100" pos="adverb">Warmly</item>
          <item weight="98" pos="adjective">Hearty</item>
          <item weight="94" pos="adjective">Hospitable</item>
          <item weight="93" pos="adjective">Cordial</item>
          <item weight="85" pos="adverb">Heartily</item>
          <item weight="84" pos="verb">Greet</item>
        </items>
      </result>
    </results>
  </response>
</wordassociationssearch>

Коды ответов

Описание возможных кодов ответов.

Значение	Описание
200	Операция выполнена успешно
401	Неправильный API-ключ
429	Превышено ограничение на количество запросов за месяц
501	Заданный язык не поддерживается

HTTP заголовки ответа

Описание HTTP заголовков, доступных на ответе.

Name	Description
X-Quota-Limit	Максимальное количество запросов согласно тарифному плану.
X-Quota-Remaining	Оставшееся количество запросов.
X-Quota-Reset	Время в секундах до окончания интервала подписки.