Online Language Dictionaries

WordReference API

Overview

We are happy to provide an API to be used by developers and are looking forward to seeing what innovative and useful tools might result.  For those accustomed to Google Translate's API, please understand that this is very different.  WordReference offers dictionary translations of words and phrases, not machine translation of sentences.

Implementation

The API comes in two varieties: a JSON format and a regular-HTML/web format.

The URL for the HTML API is
http://api.wordreference.com/{api_version}/{API_key}/{dictionary}/{term}
and for the JSON API
http://api.wordreference.com/{api_version}/{API_key}/json/{dictionary}/{term}
where {term} is the term being searched for, {dictionary} is the dictionary you want to search, and {api_version} is the desired version of the API. If {api_version} is omitted, the API will redirect to the latest version automatically. Version upgrades will be posted here; the current version is 0.8.

You must include the API key in the requesting URL.  See below for how to get an API key.  If you are including a version number in the request, the API key must go after the version number.

Additionally, for JSPONp, the JSON API can take an optional callback function in the query string; simply add "?callback={yourCallback}" to the end of the URL.

Examples:
api.wordreference.com/0.8/1/enfr/grin
api.wordreference.com/0.8/1/json/enfr/grin

The dictionary that you want to look up your term in is specified by a combination of the two-letter code for the original language and the two-letter code for the target language. For example, if you are looking up the word "house" from English to French, the URL would be '/enfr/house', where en stands for English, and fr for French. The two letter language abbreviations are below:

Please note:

1. Only to and from English. We do not currently offer any combination that does not include English (such as Spanish-French).
   
2. The API does not fully support the English - Spanish dictionaries yet. Both the English to Spanish and Spanish to English dictionaries are accessible through the API, but are still undergoing some refinements and improvements. Additionally, neither form of the API provides support for the English, Spanish, and Italian monolingual dictionaries, the Spanish synonyms, or the Russian and German dictionaries. Searches made to these dictionaries from the HTML API will return a link to the appropriate page on the main website.
   
3. Greek and Czech are abbreviated gr and cz instead of their normal language codes.

The encoding is UTF-8, so "más" must show as "m%C3%A1s".
You can only use combinations of language codes for dictionaries that WordReference actually has, so for instance, "plko" is not possible since we have no Polish>Korean dictionary.

English thesaurus support

We are happy to announce support for the WordReference English Thesaurus in the API. The URL structure is the same as for all other dictionaries, simply put "/thesaurus/" where you would normally put the four-letter dictionary code.

HTML API

In the HTML API, you can perform searches by either manually changing the URL to indicate which dictionary and what term you want to search for, or you can use a search-box and dropdown dictionary selector on the page itself.

If you search a term on the opposite side of the dictionary, the HTML API will automatically redirect you to the correct page. For instance, if you went to the page http://api.wordreference.com/1/enfr/aller, you would be redirected to the page /fren/aller.

JSON API

The structure of the JSON API differs between requests to the thesaurus and requests to all other dictionaries. An example of the typical output from most dictionaries is displayed below. See here for an explanation of the JSON output for the thesaurus.

{
    "term0" : {
        "PrincipalTranslations" : {
            "0" : {
                "OriginalTerm" : {
                    "term" : "keys",
                    "POS" : "",
                    "sense" : "door",
                    "usage" : ""
                },
                "FirstTranslation" : {
                    "term" : "clés",
                    "POS" : "nfpl",
                    "sense" : "de serrure"
                },
                "Note" : ""
            },
            "1" : {
                "OriginalTerm" : {
                    "term" : "keys",
                    "POS" : "",
                    "sense" : "on computer, piano, phone etc.",
                    "usage" : ""
                },
                "FirstTranslation" : {
                    "term" : "touches",
                    "POS" : "nfpl",
                    "sense" : "ordinateur piano téléphone etc."
                },
                "Note" : ""
            },
            "2" : {
                "OriginalTerm" : {
                    "term" : "keys",
                    "POS" : "",
                    "sense" : "",
                    "usage" : "figurative meaning"
                },
                "FirstTranslation" : {
                    "term" : "clés",
                    "POS" : "nfpl",
                    "sense" : "secrets sens figuré"
                },
                "Note" : ""
            }
        }
    },
    "original" : {
        "Compounds" : {
            "0" : {
                "OriginalTerm" : {
                    "term" : "piano keys",
                    "POS" : "",
                    "sense" : "",
                    "usage" : ""
                },
                "FirstTranslation" : {
                    "term" : "le clavier du piano, les touches",
                    "POS" : "",
                    "sense" : ""
                },
                "Note" : ""
            }
        }
    },
    "Lines" : "End Reached",
    "END" : true
}

The API will return a series of zero or more objects of the type "term0" : {category-block}, which will increment in the style "term1", "term2", etc, depending on how many distinct terms have been found in the dictionary. Additionally, if any compound forms of the searched term are found in the dictionary, the API will return an object of the type "original" : {category-block}.

The category blocks that the API returns can be any of the following:

• PrincipalTranslations - the main entries found for the searched term.
• AdditionalTranslations - other entries for the term aside from the principal translations.
• Entries - entries when they are not divided between principal and additional translations.
• OtherSideEntires - for some dictionaries, we do a 'reverse dictionary' in that we return entries from the opposite side (e.g searching Czech to English will search entries on the English to Czech dictionary).
• Compounds - compound terms or phrases that include the searched term. These will only show up under the "original" object, not under any of the "term#" objects.

The term0, term1, term2, etc. objects can contain the first four category-block types, while the original object type will only contain a Compounds category-block.

Within each category block, the data comes in a pair in the form of {"0" : {entry block}} for each entry found, with "0" incrementing upwards for however many entries are found.. In the example above, the API returns four entry blocks for keys because four entries were found: within PrincipalTranslations, three nouns were found, and within the Compounds section, one entry was found for 'piano keys'.

The entry-block has three types of objects:

1. The OriginalTerm object is the returned search term. This object includes the term itself ("term"), the part of speech ("POS"), the sense or meaning of the returned term ("sense") and any usage notes for the returned term ("usage").
2. The FirstTranslation, SecondTranslation, ThirdTranslation, and FourthTranslation objects are the dictionary entries for the searched term. For any returned entry, there will be at least the FirstTranslation object, and for entries with more translations there will be the Second, Third and Fourth as needed. Each translation object includes the translated term ("term"), the part of speech ("POS"), and the sense of the translated term ("sense"). Additionally, for Chinese translations, there is a pinyin element returned ("Pinyin") when a pinyin translation exists for the term (e.g. /enzh/shoelace).
3. After the translation objects, there is a Note object, which includes any qualifying note about the entry (e.g. /enfr/jade-green).

After the note, the entry-block is complete, and the entry-number ("0", "1", "2", etc.) object is closed. If there are more entries found, a new object is opened, with the subsequent number as the object name. For example, in the /enfr/keys entry above, three entries are found for the term keys under the PrincipalTranslations object, so three objects named "0", "1", and "2" are returned.

If no entry is found for the searched term, the output is : {"Note" : "No entry was found for the searched for term."}

If a term is searched for on the wrong side of the dictionary, the page returns the relative redirect-url under the element "URL". For example, if you went to http://api.wordreference.com/1/json/enfr/aller, the API would return : { "Response" : "Redirect", "URL": "/fren/aller"}

There can be up to four translations for a given entry, and there can be several entries for a given term (for instance, all compound terms that include the searched-for-term will show up).

At the end of the response, the following pairs, "Lines" : "Maximum Reached", "END" : true, are returned to indicate the end of the response.

Getting an API key

To get an API key:

1. Go to the API Registration page and fill out the necessary information.
2. After registering, you will receive your API key. Write this down and record it somewhere. You must use it to access the API!
3. If you lose your key, you can retrieve it here.
4. If you registered for a key and it is not working, you can check the status of your key here.

Terms of Service

• You must include the copyright line: © WordReference.com
• You must link back to the term's entry on WordReference's website with the translation or equivalent of: 'term' at WordReference.com
• No derivative works (without permission).
• API data can only be stored and cached for 24 hours (without permission).
• You are limited to 600 requests to the API per hour by default.
• Cannot be used in: browser toolbars.
• Cannot be used in an application or webpage whose primary function is as a dictionary or translator (without permission).

Share your work!

If you have made something cool with the API that you want to share with others, feel free to post it in the forums. You can post any full-blown applications here or post any programming language-specific code-snippets or SDKS here.

Questions? Comments? Suggestions? Send us a message.