With the release of iOS 12 last year, Apple pushed out an app called Shortcuts. In iOS 13 this year, they actually made it useful. With it, you can connect Siri actions to the Cloverly API. In this example, we'll use shortcuts to offset a trip from my house to my work. Then we can say, "Hey, Siri, offset my commute from home."

Getting started

Obviously, you'll need an iOS 13 device (iPhone, iPad, iPod Touch, HomePod). Then you can set up a Cloverly sandbox account at https://cloverly.com/signup.

This walkthrough has the following steps:

  1. Create a new Shortcut.
  2. Add action to get driving distance from your house.
  3. Send the request to offset to the Cloverly API.
  4. Extract values from the JSON response.
  5. Speak outcomes.
  6. Bonus: Go back and format variables and responses to have a nicer interaction.

Create a new Shortcut

On your iOS device, open the Shortcuts application. (Or download and open the app if you don't already have it.) Then click the + sign in the upper right to create a new project. Your base, empty project should look like this:

Add action to get driving distance

Next, click the "Add Action" button, and search for and click the "Get Distance" action. Change the "Current Location" to be your home address and the "End Location" to be your "Current Location." Additionally, I use "Miles" and "Driving" under "Show More":

Later in our application, we'll use the distance variable created by this action to pass to the Cloverly API.

Send the request to offset to the Cloverly API

Next, click the + button below our previous action to add a new one. This time, we'll create a "Get contents of URL" action. Then, we'll touch "URL" and use the following setting:

URL: https://api.cloverly.com/2019-03-beta/purchases/vehicle

Under "show more," we'll use the following variables (which are case-sensitive):

Method: POST

Headers
Key: Authorization:
Text: Bearer public_key:47800ea0ee541b4c
(Note that those are zeroes, not the letter "o." This is where you can use your own public key for your own account.)

Request Body: Form

Key: distance[value]
Text: (Touch "distance" icon in the Variables bar to use the distance variable from earlier.)

Key: distance[units]
Text: miles

Key: fuel_efficiency[value]
Text: (Enter the number representing your vehicle's mileage.)

Key: fuel_efficiency[units]
Text: either "mpg" or "km/l"

Key: fuel_efficiency[of]
Text: either "gasoline" or "diesel" depending on your fuel

This action will look like the following:

Extract values from the JSON response

If you press the "Play" button in the lower right corner, what we have so far will run. (If you receive a request to access api.cloverly.com, click OK.) Then you'll see the JSON response from Cloverly like the following:

Next, add an action called "Get Dictionary Value." Then we will extract the "equivalent_carbon_in_kg" from the "Contents of the URL" like so:

Now, if we press "Play" again in the lower right corner of the Shortcut, the end output will be a number. Mine happens to be 1.816, which represents 1.816 kilograms of carbon emitted on my drive to work.

Next, we'll convert that output to a variable by adding a "Set Variable" action. This allows us to use the "carbonKG" variable later.

Speak outcomes

Now let's speak the outputs we have so far. We'll use the "Speak Text" action to say, "Offset your {distance icon} mile trip which emitted {carbonKG icon} kilograms of carbon." Like so:

Now press the "play" button in the lower right corner, and you'll hear the outcome. To save, click "Next." Give your Shortcut a name, and you can speak that text to Siri. Here, we name it "offset my trip from home."

Wrap up

Now you can offset your trip from your home by saying, "Hey, Siri, offset my trip from home."

For a bonus, you can use more "Set Variable" actions to extract the name of the offset source from Cloverly. In the original example, we voiced that we used Butler Solar Farm. Additionally, you can use "Format" actions to round the numbers to make them more digestible.

You can also skip all of these instructions and have the whole Shortcut installed by following this link from your device (you'll need to Allow Untrusted Shortcuts in your Shortcuts settings): https://www.icloud.com/shortcuts/02baa00d1c75430ea6b576d32b3720c7.

Want to see it in action? Follow this link: https://slack-files.com/TDR17CJLV-FPPAM185D-c8ceb0b146.

Have fun playing with Cloverly and Siri!