This tutorial is for beginners who have little experience with API requests, and may not be able to fully understand API documentation. It goes into detail on how to use variables and what the user says in the API request URL. Advanced users should see this article.

Storyline has just rolled out a new feature, allowing you to have variables in URLs. This opens up many possibilities, however, in this case, I’m going to be making use of a public API which allows you to get weather data of a specific location.

Link to Project

API Documentation I Used

First of all, what is an API request? An Application Programming Interface, or API for short, is essentially a database where all sorts of data and functions are stored. Some APIs are private, say, Amazon’s API, which will contain all of their user’s data, but some are public, and anybody can access and read the data stored on them. In this tutorial, we’re going to be using an API to get data on weather in a UK city, which will be told to the user.

Before we begin, we’ll need to find the API we want to use. You can find yours by searching on Google: ‘Public {API type} API’. I searched ‘Public Weather API’ and MetaWeather came up. To find out how we need to format our URLs, which tell the device where to get the data, we need to visit the API Documentation for MetaWeather. I found it here. Under methods, we can see ‘Location’, which tells us ‘location information and 5 day forecast’. This sounds like what we want, so click on it. It tells us that the URL for the weather of a certain location is ‘/api/location/(woeid)/’. It says that ‘woeid’ stands for Where on Earth ID, which means we need to get the city ID first.

If we scroll back up a bit, we can see a ‘Location Search’ section. It tells us that the URL to find out the WOEID of a city is /api/location/search/?query=(query). If, for example, we wanted to find out the WOEID of London, the link would be /api/location/search/?query=London. The domain name of MetaWeather is MetaWeather.com, so the full link will be MetaWeather.com/api/location/search/?query=(query).

Now, we have to create a function in Storyline which replaces (query) with the city that the user says. Open up or create a project at http://getstoryline.com/projects/. In the first block, we need to ask the user what city they would like to get the weather for. You can see this in the project I made.

Let’s create a variable which will replace ‘(query)’ in the API Request URL. Go to the ‘Variables’ tab and click ‘new variable’. Find the slot type most appropriate to your skill. Mine is the UK City slot type/variable type.


As you can see, I named my variable ‘city’. My first user reply is set to {city}. This will mean that, when the user opens the skill and is prompted to name a UK city, their reply will be saved so that we can use it in the API request URL.

Now we know what the user said, let’s use it.


In the URL box, second from the top, I have https://www.metaweather.com/api/location/search/?query={{city}}. {{city}} will be replaced by the city our user chose, in this case, London, so the API request would be to https://www.metaweather.com/api/location/search/?query=london – open that link, now. Here, we can see the WOEID for London. In order to get that, we’ve saved the ID as variable ‘id’, by using id=api_response.0.woeid. You should put api_response in all of your API requests as it helps Storyline understand the reply. 0 in computer language means one, or first, and it’s the first API Response so we leave it as 0. The ID is stored under ‘woeid’ in the JSON (the webpage file type you’re looking at), so that’s the last portion of our API request.

Our next API request puts the WOEID we’ve saved into the URL and retrieves the weather status for us..
In our URL (https://www.metaweather.com/api/location/{{id}}/), {{id}} will be replaced with the five digit ID we saved in our previous API request (https://www.metaweather.com/api/location/44418/). If you visit that link, you’ll see the weather data for the city we mentioned, London. I want ‘weather_state_name: *weather*’ to be Alexa’s reply, so I’ve formatted the API request to save weather_state_name, which, at the moment, is light rain.

Finally, to repeat the information back to the user, we just have to have {{weather}} in an Alexa says step where you want Alexa to tell the user the weather. You can test this in the Developer Console or on your Alexa-enabled device.

Categories: APIsBuild

1 Comment

Making API requests with variables in the URL: POWER USERS – Voicebox · August 9, 2018 at 5:36 pm

[…] This tutorial is for advanced users who understand the basics of making API requests, and are able to read API documentation. It outlines how to implement the new feature but doesn’t go into too much detail on how it actually works. Beginner users should see this article. […]

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.