RSS

Blog

Learning to use APIs with Wikipedia

Introduction

 

API stands for “application programming interface”.

When you send a request to an endpoint, its API will interpret your request and then perform the action you have specified.

In this scenario, “endpoint” is the URL which we use to make requests.

 

I will be using the MediaWiki API in order to demonstrate how we can request information from English Wikipedia:

https://en.wikipedia.org/

The endpoint we will send our requests to will be:

https://en.wikipedia.org/w/api.php

 

 

How do I specify what information I want?

 

Let’s say we want to get the first few lines from the Wikipedia page about Amazon Alexa.

In order to tell the API what we want, we need to add some parameters to the endpoint.

 

We start the string of parameters with a question mark.

https://en.wikipedia.org/w/api.php?

Then, if you have multiple parameters, connect them using the “&” symbol.

 

Here is a snippet of JavaScript code which makes our request slightly easier to read and construct.

const myPageTitle = “Amazon_Alexa”;

const endpoint = "https://en.wikipedia.org/w/api.php"

const params = “?action=query” // query is one possible action.

+ “&prop=extracts” // “extracts” is the name of an extension used by many wikis.

+ “&exsentences=3” // this lets you get the first 3 sentences from a page.

+ “&exlimit=1”⠀

+ “&titles=” + myPageTitle// this lets you specify which page you want information from.

+ “&explaintext=1” // means “extracts plain text”, which is human-friendly for reading.

+ “&format=json” // the data will be returned in JSON format

+ “&formatversion=2” // the JSON will be easier to navigate using index notation

+ “&origin=*”; // prevents a CORS error

Now we have a complete URL which we can use to make our request:

const alexaWikiUrl = endpoint + params;⠀

console.log(alexaWikiUrl); // output: https://en.wikipedia.org/w/api.php?action=query&prop=extracts&exsentences=3&exlimit=1&titles=Amazon_Alexa&explaintext=1&format=json&formatversion=2&origin=*

Try visiting the link in your browser!

You will be presented with the information which would be returned if you were to make the request using code.

Implementation

In order to make API calls using your Alexa skill, you need to install a package which lets you do so.

There are many choices, but I recommend either node fetch or Axios. Node fetch appears to be more commonly used, but Axios is easier for me personally.

Here is an example of what a fetch request might look like using node fetch:

const wikiEndpoint = 'https://simple.wikipedia.org/w/api.php';

const wikiParams = "?action=query"

+ "&prop=extracts"

+ "&exsentences=3"

+ "&exlimit=1"

+ "&titles=" + "Amazon_Alexa"

+ "&explaintext=1"

+ "&format=json"

+ "&formatversion=2"

+ "&origin=*";

const myUrl = wikiEndpoint + wikiParams;

console.log(myUrl);

 

async function getData(url){

let res = await fetch(url);

let data = res.json();

return data;

}

 

getData(myUrl).then(data => {

console.log(data.query.pages[0].extract)

})

If you were to use Axios, it might look something like this:

async function getWikiData(){

const wikiEndpoint = 'https://simple.wikipedia.org/w/api.php';

const wikiParams = "?action=query"

+ "&prop=extracts"

+ "&exlimit=1"

+ "&exsentences=3"

+ "&titles=" + "Amazon_Alexa"

+ "&explaintext=1"

+ "&format=json"

+ "&formatversion=2"

+ "&origin=*";

const wikiLink = wikiEndpoint + wikiParams;

 

var wikiConfig = {

timeout: 6500

};

async function getJsonResponse(url, config){

const res = await axios.get(url, config);

return res.data;

}

return getJsonResponse(wikiLink, wikiConfig).then((result) => {

return result;

}).catch((error) => {

return null;

});

}

const wikiData = await getWikiData();

const wikiOutput = wikiData.query.pages[0].extract;

console.log(wikiOutput);

In both cases, the first 3 sentences from https://en.wikipedia.org/wiki/Amazon_Alexa will be logged.

The code in the node fetch example should work in your browser console.

If you want to test it out, try using this code and experimenting by changing some parameters.

Axios isn’t so easy to test, but the provided example works when implemented correctly, and should be able to serve as a good foundation.

Useful resources

https://www.youtube.com/watch?v=KlTrP6XYvEM

https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API

https://www.mediawiki.org/wiki/API:Main_page

https://www.npmjs.com/package/node-fetch

https://www.npmjs.com/package/axios

How To Enable The Skill

In the video below you can check out how to easily enable skills for your Alexa device! 

Slots

Slots allow your skill to be more interactive and allow the user to be able to input information
into your skill which allows the the skill to change depending on the users input. This means
that a single intent will show different information depending on what the user is asking for.

We have used this method to create a timesheet for a charity which allows the user to choose
a day in their input and then the skill will respond with whatever the information is that
corresponds with that specific day. This also allows the user to be able to ask the skill
"what activities are happening today" and the skill will work out what day it is and respond
with the correct information. This also works with "tomorrow" or any day from Monday to Sunday.

API integration

API's are a way to connect your alexa skill to third party applications, such as linkedin,
twitter, bbc, flickr, and many more. This allows you to display information from these sites
on your skill.

The picture used in this skill is taken from Matthew Cackett (mattc68).

This example is of using the flickr api in your skill which allows you to link your skill
to flickr. This will make it so that you are able to show pictures from the site on your skill.
This makes it possible for us to make a personal gallery skill, so that all the images you
upload to flickr can be browsed through all from your skill. You could also make it so that
the user could say the username of any account and search through all the public photos thats
been uploaded to that account.

SSML (Speech Synthesis Markup Language)

This is how you change the voice of Alexa in terms of what it sounds like and how it
pronounces, enthasises words. You can make the voice male or female with different accents,
to allow the interaction with the skill to feel more like an actual conversation you are
having with a human to gain the information you are looking for. This is a video of some of
the different voices and interjections that can be used in the skills.

When we work with you in creating your new skill we will talk about what you would like the
voice to sound like and what kind of mood you want to set throughout the skill. As with
good use of the interjections and voice clips you are able to make the skill more serious
or light hearted depending on what you want the skill to be about.