NAME

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

SYNOPSIS

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

DESCRIPTION

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.

METHODS

new

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.

get_word_details

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",
          $result->{partOfSpeech},
          $result->{definition};
 }

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

definitions

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",
          $entry->{partOfSpeech},
          $entry->{definition};
 }

rhymes_with

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";
 }

SEE ALSO

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

REPOSITORY

https://github.com/neilb/WebService-WordsAPI

AUTHOR

Neil Bowers <neilb@cpan.org>

LICENSE AND COPYRIGHT

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.

cpanm WebService::WordsAPI

perl -MCPAN -e shell
install WebService::WordsAPI