User guide for Oxford Dictionaries API v2
Migration Guide for Oxford Dictionaries API v1 to v2
What is version 2?
Oxford Dictionaries API version 2 makes it even easier to incorporate powerful language data into your applications, in even more languages.
Whilst preserving the core functionality of v1, we've made creating requests clearer, behaviour and responses more predictable, and added more functionality as standard across more endpoints.
Version 2 is the biggest leap forward since the service was originally launched, and we can't wait to see what you build with it!
This guide describes the key differences between v1 and v2 so that you can migrate easily and take advantage of the new features. Each endpoint is described in detail and FAQs are listed at the bottom in case you have any questions.
Summary of key changes
- Endpoint names and syntax separated from Entries endpoint.
- Query parameters use standard URL structure.
- Result projections separated from filters.
- Strict match option added.
- Wordlist endpoint has been removed and replaced by Oxford English Wordlist product.
- New languages: Greek, isiXhosa, Quechua, Tajik, Tatar, Telugu, Tok Pisin, Turkmen.
Making requests to version 2
Version 2 shares the same domain as version 1, making it easy to progressively switch your application from v1 to v2. It also means your App ID and App Key remain the same!
Use 'v1' in the URL to request version 1, and 'v2' to request version 2.
Make sure you switch soon. Version 1 will be deprecated in June 2019.
https://od-api.oxforddictionaries.com/api/v1
https://od-api.oxforddictionaries.com/api/v2
Global changes to all endpoints
1. Endpoint names and syntax separated from Entries endpoint
Instead of being extensions of the Entries endpoint, translations, sentences and thesaurus are now their own endpoints.
GET /api/v1/entries/en/abode/translations=es
GET /api/v2/translations/en/es/abode
2. Query parameters now use a more standard URL structure
Query parameters are now separated from the URL start by a ? and use an & separator between parameters to follow a standard URL approach.
GET /api/v1/entries/en/run/lexicalCategory=noun;definitions,etymologies
GET /api/v2/entries/en-gb/run?lexicalCategory=noun&fields=definitions,etymologies
3. Result projections separated from filters and made explicit
Result projections (which choose the data items that are returned in results) have been moved to an explicit fields parameter to avoid confusion with filters.
Filters and result projections are supported in the Entries, Lemmas and Thesaurus endpoints.
GET /api/v1/entries/en/run/definitions,etymologies
GET /api/v2/entries/en-gb/run?fields=definitions,etymologies
If the fields parameter is present, the API projects the values of the given fields in the response and excludes those that are not present. If the fields parameter is not provided the API retrieves the full entry with all the available fields for a given word_id. However, if the fields parameter is empty, the API retrieves the minimum payload, which means that it retrieves just the required fields such as lexicalCategory, id, homographNumber and word in the response.
A Utilities endpoint has been provided to provide the available fields
/api/v2/fields/{endpoint}:
GET /api/v2/fields/entries
4. Explicit Strict Match option provided
Version 2 allows the user to explicitly specify whether the response should or should not return near-homographs. A 'near-homograph' is a word that can have a different meaning if it appears with a symbol, for example rose and rosé. The default is to include near-homographs (strictMatch=false).
Strict match is supported in the Entries, Translations, Sentences, and Thesaurus endpoints.
For example (Entries):
GET /api/v2/entries/en-us/rose?strictMatch=true
will return just rose and no near-homographs.
GET /api/v2/entries/en-us/rose?strictMatch=false
will return rose and near-homographs like rosé.
For example (Translations):
GET /api/v2/translations/en/es/rose?strictMatch=true
will return translations of just rose and no near-homographs.
GET /api/v2/translations/en/es/rose?strictMatch=false
will return translations of both rose and near-homographs like rosé.
Entries endpoint
1. English GB and US have separate dataset names
Instead of using the regions parameter to define whether you want to search for British (GB) or American (US) English, v2 embeds this within the dataset name, using the ISO 639 standard. Use "en-gb" for British English and "en-us" for American English.
For example (US):
GET /api/v1/entries/en/basil/regions=us
GET /api/v2/entries/en-us/basil
For example (GB):
GET /api/v1/entries/en/basil/regions=gb
GET /api/v2/entries/en-gb/basil
For example:
GET /api/v2/entries/en/run
This will result in a redirect being returned to the user:
HTTP 301 Moved Permanently Location: /api/v2/entries/en-gb/run
Translations Endpoint
1. URL structure change
The URL structure has changed so that the Translations endpoint is more explicitly separate from the Entries endpoint. The target language is now part of the URL not a parameter.
For example:
GET /api/v1/entries/en/abode/translations=es
GET /api/v2/translations/en/es/abode
Sentences endpoint
1. URL structure change
The Sentences endpoint is now more explicitly separate from the Entries endpoint. Instead of calling /entries/{source_language}/{word_id}/sentences, you just need to call /sentences/{source_language}/{word_id}.
For example:
GET /api/v1/entries/en/run/sentences
GET /api/v2/sentences/en/run
Thesaurus endpoint
1. URL structure change
The Thesaurus endpoint is now more explicitly separate from the Entries endpoint. Instead of calling /entries/{source_language}/{word_id}/synonyms, you just need to call /thesaurus/{source_language}/{word_id}.
For example:
GET /api/v1/entries/en/pity/synonyms;antonyms
GET /api/v2/thesaurus/en/pity?fields=synonyms,antonyms
If the fields parameter is not provided the API retrieves the full entry with all the available fields, including both synonyms and antonyms.
Inflections (Lemmatron) endpoint
1. URL structure change
The Inflections ("Lemmatron") endpoint has been renamed to Lemmas to more accurately describe its function.
For example:
GET /api/v1/inflections/en/banks
GET /api/v2/lemmas/en/banks
Search endpoint
1. URL structure change
The Search endpoint URL structure has been changed for searching translations. Search for all other datasets (e.g., monolingual) remains the same.
For example (translations search):
GET /api/v1/search/en/translations=es?q=el
GET /api/v2/search/translations/en/es?q=el
For example (monolingual search - British English):
GET /api/v1/search/en?q=an
GET /api/v2/search/en-gb?q=an
Wordlist endpoint
The wordlist endpoint has been replaced by a new product, the Oxford English Wordlist, which is launching soon and is perfect for games and app development. Contact us to find out more and get access before everyone else!
Utilities endpoints
1. Regions utility endpoint removed
The Regions endpoint has been removed because the region is now part of the dataset name (see the Entries endpoint section).
2. New fields utility endpoint added
A new utility endpoint is provided to list the available fields for result projections in each endpoint. Result projections are supported in the Entries, Lemmas and Thesaurus endpoints.
The utility endpoint has the form /api/v2/fields/{endpoint}:
GET /api/v2/fields/entries
New languages
As part of the Oxford Global Languages programme, we're pleased to launch the following new language datasets in v2:
- Greek (EL)
- isiXhosa (XH)
- Quechua (QU)
- Tajik (TG)
- Tatar (TT)
- Telugu (TE)
- Tok Pisin (TPI)
- Turkmen (TK)
For the full list of languages now available in Oxford Dictionaries API, and which endpoints they each work with, see the Supported Languages page.
Migration FAQs
Yes! If you want to continue developing using the Oxford Dictionaries API you will need to update your plan and code to use v2 before 30 June 2019. You can find guidance on how to update your code here.
Version 2 is not available on the Free account and will result in a 403 Authentication error. You will need to update your account to either a Prototype or Developer plan to access v2. You can see how to update your plan here.
Version 2 is live from 16 April so you can start updating your application now.
We will shut down v1 on 30 June 2019, at that time any application that depends on v1 will not work.
Yes! If you want to continue developing using the Oxford Dictionaries API you will need to update your code to use v2 before 30 June 2019. You can find guidance on how to update your code here. Version 2 will be live from 16 April so you can start updating your code as soon as it’s live.
We will shut down the v1 on 30 June 2019. At that time any application that depends on v1 will not work.
With the launch of v2 we are changing our account plans, you will have preview access to v2 on your current plan until 30 June 2019. On 30 June we will automatically update your plan to our new Developer plan. You can read more about our Developer plan here.
PLEASE do not change your account plan to Developer as you may receive an invoice for both plans and be charged incorrectly. You will receive your first Developer plan invoice in August (for your July usage).
Yes! If you want to continue developing using the Oxford Dictionaries API you will need to update your code to use v2 before 30 June 2019. You can find guidance on how to update your code here. Version 2 will be live from 16 April so you can start updating your code as soon as it’s live.
We will shut down v1 on 30 June 2019, at that time any application that depends on v1 will not work.
16 April 2019 v2 will be live.
Free users can now update to a Prototype or Developer plan to gain access to v2. Basic, Pro, Premium, Researcher and Enterprise accounts will have preview access to v2.
30 June 2019 we will shut down v1.
Basic, Pro and Premium plans will automatically be updated to our Developer plan. You can read more about our v2 plans here.
For more in depth information about the changes please see our migration guide and our v2 documentation here.
The launch of v2 will be our biggest update to the service since it launched in 2016 and we needed to make some changes to keep improving the API and how it works behind the scenes. We are really excited about the improvements we have made and want to make sure you can take advantage of the new languages and better functionality.
We’ve had feedback about our usage caps so with v2 we are removing that blocker to make it easier to scale your usage. We love seeing your applications grow and want to make sure our API plans enable that. The new Prototype and Developer plans mean you will be charged for your actual usage and can take advantage of pricing discounts as your usage grows.
Version 2 will be available on 16 April v2 but you will need to update your account to the plan that best fits your needs in order to get access. You can find more information about our new plans and pricing here.
Version 1 will be remain live until 30 June 2019. Any applications using v1 after this date will not work.
16 April v2 is live and you now have preview access to v2.
v1 will remain live until 30 June 2019.
On 30 June 2019 we will automatically update your plan to our new Developer plan.
PLEASE do not change your account plan to Developer as you may receive an invoice for both plans and be charged incorrectly.