Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


RubyGems | WLAPI Project Page | Source Code | Bug Tracker | Mailing List

Gem Version Build Status Code Climate Dependency Status

DISCLAIMER We are working on the new RESTful client. Please be patient!


WLAPI is a programmatic API for web services provided by the project Wortschatz, University of Leipzig. These services are a great source of linguistic knowledge for morphological, syntactic and semantic analysis of German both for traditional and Computational Linguistics (CL).

Use this API to gain data on word frequencies, left and right neighbours, collocations and semantic similarity. Check it out if you are interested in Natural Language Processing (NLP) and Human Language Technology (HLT).

This library is a set of Ruby bindings for the following featuren. You may also be interested in other language specific bindings:

The original Java based clients with many examples can be found on the project overview page.

Implemented Features

You can use the following search methods:

  • #baseform;

  • #cooccurrences;

  • #cooccurrences_all;

  • #crossword;

  • #domain;

  • #experimental_synonyms;

  • #frequencies;

  • #left_collocation_finder;

  • #left_neighbours;

  • #right_collocation_finder;

  • #right_neighbours;

  • #sentences;

  • #similarity;

  • #synonyms;

  • #thesaurus;

  • #wordforms;

  • #ngrams;

  • #ngram_references;

The services NGrams and NGramReferences are under development and will be available soon. Both methods throw an NotImplementedError for now.

The interface will be slightly changed in the version 1.0 to be more readable. For example, #cooccurrences_all may become #all_cooccurrences.

There are two additional services by Wortschatz Leipzig: MARS and Kookurrenzschnitt. They will not be implemented due to internal restrictions of the service provider.


WLAPI is provided as a .gem package. Simply install it via RubyGems.

To install WLAPI ussue the following command:

$ gem install wlapi

The current version of WLAPI works with the second Savon generation. You might want to install versions prior to 0.8.0, if you are bound on the old implementations of savon:

$ gem install wlapi -v 0.7.4

If you want to do a system wide installation, do this as root (possibly using sudo).

Alternatively use your Gemfile for dependency management.

We are working on a .deb package, which will be released soon.


Basic usage is very simple:

$ require 'wlapi'
$ api =
$ api.synonyms('Haus', 15) # returns an array with string values (UTF8 encoded)
$ api.domain('Auto') # => Array

If you are going to send mass requests, please contact the support team of the project Wortschatz, get your private credentials and instantiate an authenticated client:

$ require 'wlapi'
$ api =, password)

See documentation in the WLAPI::API class for details on particular search methods.


While using WLAPI you can face following errors:

  • WLAPI::UserError;

  • WLAPI::ExternalError.

The errors here are presented in the order they may occur during WLAPI's work.

First WLAPI checks the user input and throws a WLAPI::UserError if the arguments are not appropriate.

Then it fetches a response from a remote server, it can result in a WLAPI::ExternalError. In most cases it will be a simple wrapper around other errors, e.g. Savon::SOAP::Fault.

All of them are subcalsses of WLAPI::Error which is in turn a subclass of the standard RuntimeError.

If you want to intercept any and every exception thrown by WLAPI simply rescue WLAPI::Error.


If you have question, bug reports or any suggestions, please drop me an email :) Any help is deeply appreciated!

If you need some new functionality please contact me or provide a pull request. You code should be complete and tested. Please use local_* and remote_* naming convention for your tests.

Supported Ruby Versions

The library is testend on the following Ruby interpreters:

  • MRI 1.8.7

  • MRI 1.9.3

  • MRI 2.0.x

  • MRI 2.1.x

  • JRuby (both 1.8 and 1.9 modes)

  • Rubinius


For details on future plan and working progress see CHANGELOG.


This library is work in process! Though the interface is mostly complete, you might face some not implemented features.

Please contact me with your suggestions, bug reports and feature requests.


WLAPI is a copyrighted software by Andrei Beliankou, 2010-2016

You may use, redistribute and change it under the terms provided in the LICENSE file.