++ed by:
Author image Neil Bowers
and 1 contributors


WebService::WordsAPI - a draft Perl 5 interface to the WordsAPI service


 use WebService::WordsAPI;
 my $api = WebService::WordsAPI->new(key => '...');
 my $details = $api->get_word_details('plan');
 print $details->{results}[0]{definition}, "\n";


This module is an interface to the WordsAPI service, which provides an API for getting information about words, including definitions, pronunciations, number of syllables, and more.

This is very much a first cut at an interface, so (a) the interface may well change, and (b) contributions are welcome.

To use this module you need an API key from https://rapidapi.com, which is where WordsAPI is hosted. They have a free level, which gets you 2500 lookups per day.

All of the instance methods take a word and by default return a Perl data structure. You can request to get back the underlying JSON response instead, by setting the return_type attribute.



You must provide the key that you got from rapidapi, and can optionally specify the return_type, which should be 'perl' or 'json'.

 my $api = WebService::WordsAPI->new(
               key         => '...',
               return_type => 'json',

I figured people wouldn't want to vary the return type on a method-by-method basis, which is why it's not something you can specify on individual methods.


This is the main function of the API. It takes a word and returns a structure with various bits of information. You may get multiple entries in the result. For example when looking up "wind", it can be a verb, as in to wind a clock, and a noun, as in the wind blew from the East.

 my $details = $api->get_word_details('wind');
 foreach my $result (@{ $details->{results} }) {
   printf "%s: %s\n",

Look at the API documentation to see exactly what is returned.


This returns just the definitions for the word. As noted above, this may return multiple definitions:

 my $result = $api->definitions('wind');
 foreach my $entry (@{ $result->{definitions} }) {
   printf "%s: %s\n",


This takes a word and returns one or more lists of words that rhyme with the given word:

 my $results = $api->rhymes_with('wind');
 my $rhymes  = $results->{rhymes};

 foreach my $pos (keys %$rhymes) {
   my $words = @{ $rhymes->{ $pos } };
   print "\n$pos: @words\n";


www.wordsapi.com is the home page for the service; documentation for the API can be found at https://www.wordsapi.com/docs.




Neil Bowers <neilb@cpan.org>


This software is copyright (c) 2019 by Neil Bowers <neilb@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.