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

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

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

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

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

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

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

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 Время в секундах до окончания интервала подписки.