Introduction: How to Create an Instant API Using Wolfram Language
For those who are new to programming, this video is a nice introduction to Application Programming Interfaces (APIs) - https://wolfr.am/7xO0cta8
An instant API lets you unleash the power of the Wolfram Language into your own coding project/app/website from a web URL. You create an instant API and deploy it on the web using the Wolfram Language functions APIFunction and CloudDeploy. Instant APIs can be private (so only you can use them) or public (so anyone can use them). Note: running an instant API uses Wolfram Cloud Credits from your account.
An API requires three things:
1. What the API takes in as the input i.e. a specification of parameters and their types
2. What you want the API to do with the input i.e. a specification of the code the API should run
3. What the results should look like i.e. a specification of how the result from the API should be returned
More about how these three parts can be defined can be found here - http://reference.wolfram.com/language/guide/Creat... However, it is not necessary to go through this to make this instructable. Understanding the functions involves a higher coding skill level.
We will use a simple example of an instant API that will give you the locations of all the geographic formations within a given radius of a given location so that we can plan a nature vacation ! We can build more functions into this API so that it can do a lot more such as plan the shortest path and give travel directions. However, since this is a beginner's introduction to APIs, we will just have the one function for this API. This instructable is split into 3 parts detailing each part of the API.
Step 1: First Part of the API - the Input
What we need is for the user to input the desired location and the radius around which to search for geographical formations. For this, we need to interpret one of the user inputs as a location and the other input as a number. We use the Interpreter[] function for the location. Since we have two inputs, it will be a list that is denoted inside { }. Focus on the code that is in bold. This shows that this APIFunction takes two inputs "location" and "radius" which is interpreted as a location and number respectively. Try changing the location from Champaign to your hometown by changing the text within those quotes. We shall go through the rest of the code in the next steps.
Code:
APIFunction[{"location" -> Interpreter["Location"], "radius" -> "Number"},"The location and radius are : " [#location][ #radius] &][<| "location" -> "Champaign", "radius" -> "50"|>]
Step 2: Second Part of the API - the Function
We now move on to what we want this APIFunction to do. We use the functions Quantity[], GeoPosition[], GeoNearest[] and EntityValue[]. Let us go through each function and what it does.
Quantity[] - represents a quantity with size magnitude and the unit specified by unit.
GeoPosition[] - returns the geodetic position of the specified geographical entity.
GeoNearest[] - returns the geographic entity of type enttype closest to the geo location within a particular radius. For more information on GeoNearest and how it works, please go to http://reference.wolfram.com/language/ref/GeoNear... We will be using the function form, GeoNearest[spec,loc,{n,r}].
Entity Value[] - gives the value of the specified property for the given entity.
APIFunctions need pure functions and you denote a pure function by "&".
Code:
APIFunction[{"location" ->Interpreter["Location" | "GeoCoordinates" | "StreetAddress" | "ComputedLocation"], "radius" -> "Number"}, EntityValue[GeoNearest["Beach" | "Canal" | "Cave" | "Dam" | "Desert" | "Forest" | "Glacier" | "Lake" | "Mountain" | "Park" | "Reef" | "ReserveLand" | "Waterfall", GeoPosition[#location], {All, Quantity[#radius, "Miles"]}], "Name"] &, "Text"][<|"location" -> "Champaign", "radius" -> "20"|>]
Step 3: Third Part of the API - the Output
Next, we can define in what format the output will be. It can vary from simple text to an image to various other formats such as JSON so that you can use it directly with your code. Here, we will just define it as text to make it easier. The code in bold is the output definition.
Code:
APIFunction[{"location" -> Interpreter["Location" | "GeoCoordinates" | "StreetAddress" | "ComputedLocation"], "radius" -> "Number"}, EntityValue[GeoNearest["Beach" | "Canal" | "Cave" | "Dam" | "Desert" | "Forest" | "Glacier" | "Lake" | "Mountain" | "Park" | "Reef" | "ReserveLand" | "Waterfall", GeoPosition[#location], {All, Quantity[#radius, "Miles"]}], "Name"] &, "Text"][<|"location" -> "Champaign", "radius" -> "20"|>]
Step 4: Deploying to the Cloud
Lastly, we will deploy the program to the cloud using CloudDeploy[] so that you can run it in any web browser.
We have put all the things we want in the APIFunction[]. The first part of CloudDeploy evaluates this.
Next is the name of the cloud program we have deployed which will be there in the link you get after you evaluate this line of code.
Finally, we set the Permissions to Public so that anyone who has clicked the link can evaluate the program.
Code:
CloudDeploy[APIFunction[{"location" -> Interpreter["Location" | "GeoCoordinates" | "StreetAddress" | "ComputedLocation"], "radius" -> "Number"}, EntityValue[GeoNearest["Beach" | "Canal" | "Cave" | "Dam" | "Desert" | "Forest" | "Glacier" | "Lake" | "Mountain" | "Park" | "Reef" | "ReserveLand" | "Waterfall", GeoPosition[#location], {All, Quantity[#radius, "Miles"]}], "Name"] &, "Text"], Permissions -> "Public"]
Step 5: That's It ! Now You Have Created an Instant API on the Wolfram Cloud Which Includes All the Geographical Formations Near a Particular Location. Go Ahead and Plan Your Nature Vacation!
As the API does not have any input values, it gives out an Error Report but putting in the values "Champaign" and "20", we get the result!
To make you more comfortable in the Wolfram Development Platform, clicking on the link below will give you the code for this example. But don't just stop there! Tinker around and make your awesome changes to your Wiki WordCloud using different Appearance Rules. Click on the "New" icon on the right to create a new notebook and code away!