Sketch Engine API Documentation

Back to API overview

Authentication

Authentication is an optional feature that can be ommited in local installations. In such a case, simple requests can be issued to the Sketch Engine. However, usually servers require some sort of user authentication. Local installations typically use Basic http authentication, while our servers authenticate users via Corpus Architect.

No authentication

Minimalistic non-authenticated API request on local computer:

Example in Java:

import java.net.*;
import java.io.*;

public class GetURL {
    public static void main(String[] args) throws Exception {
         // url with the query
        String url_string = "http://localhost/run.cgi/wordlist?corpname=bnc;wlattr=word;wlminfreq=5;wlmaxitems=100;wlpat=test.*;format=json";

        // connecting the SketchEngine Server
        URL url = new URL(url_string);
        InputStream stream = url.openStream();
        InputStreamReader isr = new InputStreamReader(stream);
        BufferedReader reader = new BufferedReader(isr);
            
        // data receiving
        System.out.println(reader.readLine()); // json data are on the first line
    }
}

Example in python:

import urllib2

url = "http://localhost/run.cgi/wordlist?corpname=bnc;wlattr=word;wlminfreq=5;wlmaxitems=100;wlpat=test.*;format=json"
request = urllib2.Request(url)

# data receiving
file = urllib2.urlopen(request)
data = file.read()
file.close()

print data

Basic http authentication

Common variant on local installations but not compatible with the beta.sketchengine.co.uk server.

Example in Java:  (view full source)

import java.net.Authenticator;
import java.net.PasswordAuthentication;

...
        final String usr = "<username>";
        final String passwd = "<password>";
        
            // authentication issues
        Authenticator auth = new Authenticator() {
            protected PasswordAuthentication  getPasswordAuthentication () {
                return new PasswordAuthentication(usr, passwd.toCharArray());
            }
        };
        Authenticator.setDefault(auth);
...

Example in Python:  (view full source)

import urllib, urllib2, base64
...
usr = '<username>'
passwd = '<password>'
...
request = urllib2.Request(url)

# authentication
base64string = base64.encodestring('%s:%s' % (usr, passwd))[:-1]
request.add_header("Authorization", "Basic %s" % base64string)
...

Corpus Architect authentication

Authentication method used on our servers ( http://the.sketchengine.co.uk and http://beta.sketchengine.co.uk).

Example in Java:  (view full source)

import org.apache.commons.httpclient.*;
import org.apache.commons.httpclient.cookie.CookiePolicy;
import org.apache.commons.httpclient.methods.*;

...

class example3_ca {

    static final String root_url = "beta.sketchengine.co.uk";
    static final String ske_username = "<username>";
    static final String ske_password = "<password>";
   
    public static void main(String[] args) {
        
        String corp = "bnc";
        String method = "view";
        String base_url = "/auth/preloaded_corpus/" + corp + "/ske/";

        ...

        // make HTTP connection
        HttpClient client = new HttpClient();
        client.getHostConfiguration().setHost(root_url, 80, "http");
        client.getParams().setCookiePolicy(CookiePolicy.BROWSER_COMPATIBILITY);
        
        // retrieve session id
        GetMethod authget = new GetMethod("/login/");
        try {
            client.executeMethod(authget);
        } catch (IOException ex) {
            System.err.println("Error: couldn't retrieve session ID from Sketch Engine server.");
            System.exit(1);
        }
        authget.releaseConnection();
        
        // login    
        PostMethod authpost = new PostMethod("/login/");
        NameValuePair submit   = new NameValuePair("submit", "ok");
        NameValuePair username = new NameValuePair("username", ske_username);
        NameValuePair password = new NameValuePair("password", ske_password);
        authpost.setRequestBody(new NameValuePair[] {submit, username, password});
           try {
             client.executeMethod(authpost);
        } catch (IOException ex) {
            System.err.println("Error: couldn't login to Sketch Engine server.");
            System.exit(2);
        }
        authpost.releaseConnection();

        // retrieve data
...         

Example in Python:  (view full source)

import urllib, urllib2, cookielib
...
import Cookie

username = '<username>'
password = '<password>'
corp = 'bnc'

root_url = 'http://beta.sketchengine.co.uk'

...

# authentication
cj = cookielib.CookieJar()
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cj))
login_data = urllib.urlencode({ 'username' : username,
                                'password' : password,
                                'submit' : 'ok',
                              })
data = opener.open('%s/login/' % root_url)
data = opener.open('%s/login/' % root_url, login_data)

...

file = opener.open(url)
data = file.read()
file.close()

...

---

Back to API overview

More API examples

Next section