Word Associations API Developer's Guide

This document is written for developers who want to add word associations lookup feature to their websites or apps.

In this section:

Overview
JSON interface
XML interface
Response codes
Response headers

Overview

API key is required in order to access API methods. The API key can be obtained by subscribing to one of available tariff plans. To subscribe and manage your subscriptions please sign in to your Word Associations API Account.

To access the Word Associations API over HTTPS, you can use:

The JSON interface (the response is returned in language-independent JSON data format).
The XML interface (the response is returned as an XML document).

All the interfaces have the same functionality and use the same set of input parameters.

JSON interface

The response is returned in JSON format.

Methods GET and POST of HTTP request are supported.

Request syntax

https://api.wordassociations.net/associations/v1.0/json/search?
apikey=<API key>
 & text=<word or phrase>
 & lang=<language>
 & [type=<result type>]
 & [limit=<maximum number of results>]
 & [pos=<parts of speech>]
 & [indent=<yes or no>]

apikey	API key. Please register and subscribe to one of available tariff plans to get a valid API key.
text	Word or phrase to find associations with. Tip. You can use multiple parameters text in a request (from 1 to 10 inclusive). This way you can get associations for several input words or phrases in one response. Restrictions: Regardless of the size of the text associations lookup is always performed by the first 10 words of the text. For POST requests, the maximum size of the text being passed is 10,000 characters. In GET requests, the restriction applies not to the text itself, but to the size of the entire request string, which can contain other parameters besides the text. The maximum size of the string is from 2 to 10 KB (depending on the browser version).
lang	Query language. Set to the language code of corresponding language. Possible values: en — English; fr — French; de — German; it — Italian; pt — Portuguese; ru — Russian; es — Spanish;
type	Type of result. Possible values: stimulus — An input data (the text parameter) is considered as a response word. The service returns a list of stimuli words, which evoke a given response word; response — An input data (the text parameter) is considered as a stimulus word. The service returns a list of response words, which come to mind for a given stimulus word. Default value: type=stimulus
limit	Maximum number of results. Allows to limit the number of results (associations) in response. The value of this parameter is an integer number from 1 to 300 inclusive. Default value: limit=50
pos	Parts of speech to return. Allows to limit results by specified parts of speech. The value of this parameter is a list of parts of speech separated by comma. The following parts of speech codes are supported: noun — noun; adjective — adjective; verb — verb; adverb — adverb; Default value: pos=noun,adjective,verb,adverb
indent	Indentation switch for pretty printing of JSON and XML response. Allows to either turn on or off space indentation for a response. The following values are allowed: yes — turns indentation with spaces on; no — turn indentation with spaces off; Default value: indent=yes

Note.All special characters must be escaped.

Request example (GET)

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

Request example (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

Response example

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 interface

The response is returned in XML format.

Methods GET and POST of HTTP request are supported.

Request syntax

https://api.wordassociations.net/associations/v1.0/xml/search?
apikey=<API key>
 & text=<word or phrase>
 & lang=<language>
 & [type=<result type>]
 & [limit=<maximum number of results>]
 & [pos=<parts of speech>]
 & [indent=<yes or no>]

apikey	API key. Please register and subscribe to one of available tariff plans to get a valid API key.
text	Word or phrase to find associations with. Tip. You can use multiple parameters text in a request (from 1 to 10 inclusive). This way you can get associations for several input words or phrases in one response. Restrictions: Regardless of the size of the text associations lookup is always performed by the first 10 words of the text. For POST requests, the maximum size of the text being passed is 10,000 characters. In GET requests, the restriction applies not to the text itself, but to the size of the entire request string, which can contain other parameters besides the text. The maximum size of the string is from 2 to 10 KB (depending on the browser version).
lang	Query language. Set to the language code of corresponding language. Possible values: en — English; fr — French; de — German; it — Italian; pt — Portuguese; ru — Russian; es — Spanish;
type	Type of result. Possible values: stimulus — An input data (the text parameter) is considered as a response word. The service returns a list of stimuli words, which evoke a given response word; response — An input data (the text parameter) is considered as a stimulus word. The service returns a list of response words, which come to mind for a given stimulus word. Default value: type=stimulus
limit	Maximum number of results. Allows to limit the number of results (associations) in response. The value of this parameter is an integer number from 1 to 300 inclusive. Default value: limit=50
pos	Parts of speech to return. Allows to limit results by specified parts of speech. The value of this parameter is a list of parts of speech separated by comma. The following parts of speech codes are supported: noun — noun; adjective — adjective; verb — verb; adverb — adverb; Default value: pos=noun,adjective,verb,adverb
indent	Indentation switch for pretty printing of JSON and XML response. Allows to either turn on or off space indentation for a response. The following values are allowed: yes — turns indentation with spaces on; no — turn indentation with spaces off; Default value: indent=yes

Note.All special characters must be escaped.

Request example (GET)

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

Request example (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

Response example

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>

Response codes

Explanations of possible response codes.

Value	Description
200	Operation completed successfully
401	Invalid API key
429	The monthly limit on the number of requests is exceeded
501	The specified language is not supported

Response headers

Explanations of HTTP headers available on response.

Name	Description
X-Quota-Limit	The maximum number of requests according to subscription plan.
X-Quota-Remaining	Number of requests remaining.
X-Quota-Reset	The number of seconds to elapse for the quota reset.