Resources for Developers
Here you can find API client libraries (sometimes referred to as "bindings" or "wrappers") which can be used to retrieve dictionary data in any of several programming languages, as well as miscellaneous downloads to help you understand and integrate dictionary data in your project.
Downloads
This Dictionary DTD describes the XML contained in the entryContent field of entry responses (when the XML format is selected).
This HTML5 Javascript audio helper enables HTML5 audio playback of words in dictionary entries.
This sample CSS can be used to style HTML5-formatted dictionary entries, and this CSS is for styling the entries in XML.
API Clients
This page contains sample source code for the API client library in several common languages:
These "proof of concept" examples show how to make an easy interface between your application and the API server.
You will need to provide the API base URL, e.g. https://dictionary.cambridge.org/api/v1/, and your Access Key (which is a long string of letters and numbers used in the API request), which you can request on signing up.
For security reasons, it is recommended that these libraries are only used in server-side applications in a client-server architecture. The API methods should not be used in client-side applications, as this exposes the key to the end-user.
Java Dictionary API Client Library (maven project)
You can integrate this library into a Java application.
In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.
Note: the sample code requires the HttpComponents Client ( http://hc.apache.org/httpcomponents-client ) and JSON library ( http://www.json.org/java/index.html )
To use the library, you need to initialize a request handler and an API object:
DefaultHttpClient httpClient = new DefaultHttpClient(new ThreadSafeClientConnManager());
SkPublishAPI api = new SkPublishAPI(baseUrl + "/api/v1", accessKey, httpClient);
api.setRequestHandler(new SkPublishAPI.RequestHandler() {
public void prepareGetRequest(HttpGet request) {
System.out.println(request.getURI());
request.setHeader("Accept", "application/json");
}
});
Then, use the "api" object:
try {
System.out.println("*** Dictionaries");
JSONArray dictionaries = new JSONArray(api.getDictionaries());
System.out.println(dictionaries);
JSONObject dict = dictionaries.getJSONObject(0);
System.out.println(dict);
String dictCode = dict.getString("dictionaryCode");
System.out.println("*** Search");
System.out.println("*** Result list");
JSONObject results = new JSONObject(api.search(dictCode, "ca", 1, 1));
System.out.println(results);
System.out.println("*** Spell checking");
JSONObject spellResults = new JSONObject(api.didYouMean(dictCode, "dorg", 3));
System.out.println(spellResults);
System.out.println("*** Best matching");
JSONObject bestMatch = new JSONObject(api.searchFirst(dictCode, "ca", "html"));
System.out.println(bestMatch);
System.out.println("*** Nearby Entries");
JSONObject nearbyEntries = new JSONObject(api.getNearbyEntries(dictCode,
bestMatch.getString("entryId"), 3));
System.out.println(nearbyEntries);
} catch (Throwable t) {
t.printStackTrace();
}
C# Dictionary API Client Library (Microsoft Visual Studio 10 solution)
You can integrate this library into a C# application.
In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.
Note: the library requires Microsoft .NET Framework 4 ( http://www.microsoft.com/en-us/download/details.aspx?id=17851 ). The sample is written as a Microsoft Visual Studio 10 project.
To use the library, you need to initialize an API object:
SkPublishAPI api = new SkPublishAPI(baseUrl + "/api/v1/", accessKey);
Then, use the "api" object:
Console.WriteLine("*** Dictionaries");
IList<IDictionary<string, object>> dictionaries = JsonToArray(api.GetDictionaries());
Console.WriteLine(ObjectToJson(dictionaries));
IDictionary<string, object> dictionary = dictionaries[0];
Console.WriteLine(ObjectToJson(dictionary));
string dictionaryCode = (string) dictionary["dictionaryCode"];
Console.WriteLine("*** Search");
Console.WriteLine("*** Result list");
IDictionary<string, object> results = JsonToObject(api.Search(dictionaryCode, "ca", 1, 1));
Console.WriteLine(ObjectToJson(results));
Console.WriteLine("*** Spell checking");
IDictionary<string, object> spellResults = JsonToObject(api.DidYouMean(dictionaryCode, "dorg", 3));
Console.WriteLine(ObjectToJson(spellResults));
Console.WriteLine("*** Best matching");
IDictionary<string, object> bestMatch =JsonToObject(api.SearchFirst(dictionaryCode, "ca", "html"));
Console.WriteLine(ObjectToJson(bestMatch));
Console.WriteLine("*** Nearby Entries");
IDictionary<string, object> nearbyEntries = JsonToObject(api.GetNearbyEntries(dictionaryCode, (string) bestMatch["entryId"], 3));
Console.WriteLine(ObjectToJson(nearbyEntries));
Objective-C Dictionary API Client Library (Xcode 4.3 solution)
The Objective-C library is presented as an Xcode solution. It contains a test program usable on the command line.
Note: The library is developed on a Mac OS X (10.7.3) with Xcode 4.3 (4E109) and uses the JSON framework version 3.1.1 ( https://github.com/stig/json-framework )
To use the library, you need to initialize an API object and a request handler:
SkPublishAPI *api = [[SkPublishAPI alloc] initWithUrlAndAcessKey:url :accessKey];
MyRequestHandler *requestHandler = [[MyRequestHandler alloc] init];
[api setRequestHandler: requestHandler];
Then, use the "api" object:
NSLog(@"*** Dictionaries");
result = [api getDictionaries];
NSLog(@"%@", result);
NSDictionary *firstElement = [jsonUtils getFirstResult: result];
if(firstElement == NULL) {
NSLog(@"No dictionary found.");
return 1;
}
if(![firstElement objectForKey: @"dictionaryCode"]){
SBJsonWriter *jsonWriter = [[SBJsonWriter alloc] init];
NSMutableString *error = [[NSMutableString alloc] initWithString: @"dictionaryCode property was expected in the JSON object : "];
NSString *dictRespStr = [jsonWriter stringWithObject: firstElement];
[error appendString: dictRespStr];
NSLog(@"%@", error);
return 1;
}
NSString *dictCode = [firstElement objectForKey: @"dictionaryCode"];
NSLog(@"*** Search");
NSLog(@"*** Result list");
result = [api search: dictCode : @"ca" : [NSNumber numberWithInt:1] : [NSNumber numberWithInt:1]];
NSLog(@"%@", result);
NSLog(@"*** Spell checking");
result = [api didYouMean: dictCode : @"dorg": [NSNumber numberWithInt:3]];
NSLog(@"%@", result);
NSLog(@"*** Best matching");
result = [api searchFirst: dictCode : @"ca" : @"html"];
NSLog(@"%@", result);
firstElement = [jsonUtils getUniqueResult: result];
if(firstElement == NULL) {
NSLog(@"No best matching found.");
return 1;
}
if(![firstElement objectForKey: @"entryId"]){
SBJsonWriter *jsonWriter = [[SBJsonWriter alloc] init];
NSMutableString *error = [[NSMutableString alloc] initWithString: @"entryId property was expected in the JSON object : "];
NSString *dictRespStr = [jsonWriter stringWithObject: firstElement];
[error appendString: dictRespStr];
NSLog(@"%@", error);
return 1;
}
NSString *entryId = [firstElement objectForKey: @"entryId"];
NSLog(@"*** Nearby Entries");
result = [api getNearbyEntries: dictCode : entryId : [NSNumber numberWithInt:3]];
NSLog(@"%@", result);
Perl Dictionary API Client Library
You can integrate this library into a Perl application.
In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.
Note: the sample code requires the LWP ( http://search.cpan.org/~gaas/libwww-perl-6.04/ ), URI::Encode ( http://search.cpan.org/~mithun/URI-Encode-0.07/ ) and JSON ( http://search.cpan.org/~makamaka/JSON-2.53/ ) packages.
To use the library, you need to initialize a request handler and an API object:
package RequestHandler;
sub new {
my $class = shift;
return bless { }, $class;
}
sub prepareGetRequest {
my ($this, $request) = @_;
print $request->uri."\n";
$request->header(Accept => 'application/json');
}
package main;
my $ua = new LWP::UserAgent();
my $api = new IDM::SkPublish::API($baseUrl."/api/v1", $accessKey, $ua);
my $requestHandler = new RequestHandler;
$api->setRequestHandler($requestHandler);
Then, use the "api" object:
print "*** Dictionaries\n";
my $dictionaries = decode_json($api->getDictionaries());
print Dumper($dictionaries)."\n";
my $dict = $dictionaries->[0];
print Dumper($dict);
my $dictCode = $dict->{"dictionaryCode"};
print "*** Search\n";
print "*** Result list\n";
my $results = decode_json($api->search($dictCode, "ca", 1, 1));
print Dumper($results);
print "*** Spell checking\n";
my $spellResults = decode_json($api->didYouMean($dictCode, "dorg", 3));
print Dumper($spellResults);
print "*** Best matching\n";
my $bestMatch = decode_json($api->searchFirst($dictCode, "ca", "html"));
print Dumper($bestMatch);
print "*** Nearby Entries\n";
my $nearbyEntries = decode_json($api->getNearbyEntries($dictCode, $bestMatch->{"entryId"}, 3));
print Dumper($nearbyEntries);
PHP Dictionary API Client Library
You can integrate this library into a Python application.
In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.
Note: the sample code requires the cURL ( http://php.net/manual/fr/book.curl.php ) and JSON ( http://php.net/manual/en/book.json.php ) modules.
To use the library, you need to initialize a request handler and an API object:
class RequestHandler implements SkPublishAPIRequestHandler {
public function prepareGetRequest($curl, $uri, &$headers) {
print($uri."\n");
$headers[] = "Accept: application/json";
}
}
$requestHandler = new RequestHandler();
$api = new SkPublishAPI($baseUrl.'/api/v1', $accessKey);
$api->setRequestHandler($requestHandler);
Then, use the "api" object:
print "*** Dictionaries\n";
$dictionaries = json_decode($api->getDictionaries(), true);
var_dump($dictionaries);
$dict = $dictionaries[0];
var_dump($dict);
$dictCode = $dict["dictionaryCode"];
print "*** Search\n";
print "*** Result list\n";
$results = json_decode($api->search($dictCode, "ca", 1, 1), true);
var_dump($results);
print "*** Spell checking\n";
$spellResults = json_decode($api->didYouMean($dictCode, "dorg", 3), true);
var_dump($spellResults);
print "*** Best matching\n";
$bestMatch = json_decode($api->searchFirst($dictCode, "ca", "html"), true);
var_dump($bestMatch);
print "*** Nearby Entries\n";
$nearbyEntries = json_decode($api->getNearbyEntries($dictCode, $bestMatch->{"entryId"}, 3), true);
var_dump($nearbyEntries);
Then, use the "api" object:
print "*** Dictionaries\n";
$dictionaries = json_decode($api->getDictionaries(), true);
var_dump($dictionaries);
$dict = $dictionaries[0];
var_dump($dict);
$dictCode = $dict["dictionaryCode"];
print "*** Search\n";
print "*** Result list\n";
$results = json_decode($api->search($dictCode, "ca", 1, 1), true);
var_dump($results);
print "*** Spell checking\n";
$spellResults = json_decode($api->didYouMean($dictCode, "dorg", 3), true);
var_dump($spellResults);
print "*** Best matching\n";
$bestMatch = json_decode($api->searchFirst($dictCode, "ca", "html"), true);
var_dump($bestMatch);
print "*** Nearby Entries\n";
$nearbyEntries = json_decode($api->getNearbyEntries($dictCode, $bestMatch->{"entryId"}, 3), true);
var_dump($nearbyEntries);
Ruby Dictionary API Client Library
You can integrate this library into a Ruby application.
In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.
Note: the sample code requires the JSON for ruby ( http://flori.github.com/json/ ) package. It was tested with Ruby 1.9.1 ( http://www.ruby-lang.org/en/ ).
To use the library, you need to initialize a request handler and an API object:
uri = URI.parse(baseUrl)
userAgent = Net::HTTP.new(uri.host, uri.port)
userAgent.use_ssl = true
userAgent.verify_mode = OpenSSL::SSL::VERIFY_NONE
api = API.new(baseUrl+'/api/v1/', accessKey, userAgent)
Then, use the "api" object:
dictionaries = api.getDictionaries();
puts dictionaries
dictionaries = JSON.parse(dictionaries)
dict = dictionaries[0]
puts dict
dictCode = dict["dictionaryCode"];
puts dictCode
puts "*** Search"
puts "*** Result list"
results = JSON.parse(api.search(dictCode, "ca", 1, 1))
puts results
puts "*** Spell checking"
spellResults = JSON.parse(api.didYouMean(dictCode, "dorg", 3))
puts spellResults
puts "*** Best matching"
bestMatch = JSON.parse(api.searchFirst(dictCode, "ca", "html"))
puts bestMatch
puts "*** Nearby Entries"
nearbyEntries = JSON.parse(api.getNearbyEntries(dictCode, bestMatch["entryId"], 3));
puts nearbyEntries
Python Dictionary API Client Library
You can integrate this library into a Python application.
In the sample, using the library simplifies the request process to the API server and directly returns the result object in string form.
Note: the library and sample are written for Python 2.6 ( http://python.org/ ). The sample use the default JSON package ( http://docs.python.org/2/library/json.html ).
To use the library, you need to initialize a request handler and an API object:
api = API(baseUrl=baseUrl+'/api/v1/', accessKey=accessKey)
Then, use the "api" object:
print "*** Dictionaries"
dictionaries = json.loads(api.getDictionaries())
print dictionaries
dict = dictionaries[0]
print dict
dictCode = dict["dictionaryCode"]
print "*** Search"
print "*** Result list"
results = json.loads(api.search(dictCode, "ca", 1, 1))
print results
print "*** Spell checking"
spellResults = json.loads(api.didYouMean(dictCode, "dorg", 3))
print spellResults
print "*** Best matching"
bestMatch = json.loads(api.searchFirst("british", "ca", "html"), "utf-8")
print(bestMatch)
print "*** Nearby Entries"
nearbyEntries = json.loads(api.getNearbyEntries(dictCode, bestMatch["entryId"], 3))
print nearbyEntries
JavaScript Dictionary API Client Library
The JavaScript library is designed to run in a JavaScript engine or server-side application and not from a website client side.
In the sample, using the library simplifies the request process to the API server and directly give you the result object in string form.
Note: the sample code is written for SilkJS ( http://silkjs.org/ ) command-line usage and uses the cURL module ( http://silkjs.org/documentation/builtin/curl )
To use the library, you need to initialize a request handler and an API object:
var api = new SkPublishAPI ('https://'+baseUrl+'/api/v1', accessKey);
var cURL = require('cURL');
api.setRequestHandler({
executeRequest : function(config) {
var result = cURL(config);
return result.responseText;
},
prepareGetRequest : function(uri, accessKey) {
var headers = {
'Host': baseUrl,
'accessKey': accessKey,
'Content-Type': 'application/json'
};
var options = {
url: uri,
method: 'GET',
headers: headers
};
return options;
}
});
Then, use the "api" object:
print ("*** Dictionaries\n");
dictionaries = api.getDictionaries();
print (dictionaries+"\n");
dict = eval(dictionaries)[0];
for(var elt in dict){
infoVal = eval("dict."+elt);
if (typeof infoVal == 'function') { continue; }
print (elt + " : " + infoVal + " ; ");
}
print ("\n");
dictCode = dict.dictionaryCode;
print ("*** Search\n");
print ("*** Result list\n");
results = api.search(dictCode, "ca", 1, 1);
print (results+"\n");
print ("*** Spell checking\n");
spellResults = api.didYouMean(dictCode, "dorg", 3);
print (spellResults+"\n");
print ("*** Best matching\n");
bestMatch = api.searchFirst(dictCode, "ca", "html");
print (bestMatch+"\n");
print ("*** Nearby Entries\n");
nearbyEntries = api.getNearbyEntries(dictCode, eval('['+bestMatch+']')[0].entryId, 3);
print (nearbyEntries+"\n");
Legal Notice
This page and all the client libraries are published under the new BSD license below.
License
Copyright © 2012, IDM
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of IDM nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
