What is Arcade and why use it?

How many times have you hosted your data or found someone else's data, and it was *almost* what you needed? The data field you need as a percentage was somehow shared as a string field or the street names were typed in as all caps or the field you need doesn't even exist.

In the past, your only option would be to go back to your data, add a new field, calculate the new value, and re-host the data. Or, if you were using data owned by a different person, you'd end up in an endless waiting game either hoping or begging them to update their service with a new data field.

With the introduction of  Arcade , a basic scripting language that can be used across the ArcGIS Platform, you can now map the values you need or create completely new data values in minutes. You don't even need to be a programmer to use Arcade and save time. 

What is Arcade?

 Arcade  is a simple scripting language built on JavaScript that helps you calculate new data values on-the-fly, and is available throughout the ArcGIS Platform. If you create an expression within a ArcGIS Online web map, it will carry through into your apps downstream. You can create an Arcade expression anywhere you can use a data attribute within your maps. Within ArcGIS Online, ArcGIS Pro, ArcGIS Runtime, and the ArcGIS API for JavaScript, you can create a expressions for visualization, labeling, pop-ups, calculations, and aliases. This StoryMap will show an example of using Arcade within visualization.

Why use Arcade?

For example, suppose a GIS analyst in Colorado wants to map a school districts layer they found within their county’s organization. However, the NAME field containing the school district name is in all caps. Using the  built-in function Proper() , the analyst can quickly label the school districts with neatly formatted text where the first letter of each word is capitalized. 

Arcade can be used for simple excel-like statements like the one above, or basic calculations like adding two fields together. But it can also be used for  complex spatial calculations ,  variables ,  loops , and  if/else statements . Arcade also contains  geometry functions  which allow you to calculate areas, lengths, and perform simple overlay operations. 

Learn Arcade in 3 Easy Steps

Let's write an Arcade expression to get comfortable with the interface.

We will use 3 major steps to start using Arcade:

  1. Create a new expression
  2. Use an attribute from the layer to calculate a new value
  3. Test and use

Open  this ArcGIS Online map  in a browser, and click "Modify Map" at the top right to follow along. 

This example uses a  Living Atlas layer  showing virtual  coral reef stations  to help identify reefs that are at risk of  coral bleaching . The data is real-time, meaning the data values are constantly being updated by  NOAA . Warmer water temperatures can result in coral bleaching, so monitoring the temperature of the ocean with this data can help pinpoint reefs that are in danger.

The map’s legend and the pop-up are showing us the sea surface temperature of stations in the ocean. Right now, you can see that the temperature is being shown in Celsius. Celsius is used widely around the world and within the scientific community, but if the map audience is more US-centric, they might understand temperature better in Fahrenheit. 

Because the data is a live feed that is updated regularly and because the layer is owned by someone else, Arcade is the perfect tool for adjusting this map into Fahrenheit. The conversion from Celsius to Farhenheit is a simple equation:

F = C x 1.8 + 32

We can convert this data value quickly using Arcade, and because the data is updated in the layer, our map will always reflect the newest value. Let’s get started!

Step 1: Create a new expression

As mentioned before, Arcade expressions act as a new attribute within the map. So the places you’d select a field, you’ll find either “New Expression” or “Add Expression” to start. 

  • To use an expression for the map’s symbology, start by going into the Change Style options for the “Coral Reef Station – Original” layer under Content.

To use an expression for the map’s symbology, start by going into the Change Style options for the “Coral Reef Station – Original” layer under Content.

Select the dropdown containing the layer’s attributes. At the bottom, you’ll see “New Expression”. Click this to get started and open the expression window.

Note: A similar technique is used for labeling and layer transparency. For pop-ups, there is a button to add a new expression under the Attribute Expressions section of the pop-up configuration.

The expression window will appear, and you’ll see a few things. At the top is the name of the expression. This is the name of the expression and will appear in the map’s legend. It is good practice to start by naming your expression something meaningful.

Click Edit next to the “Custom” expression name and rename it “Sea Surface Temperature (F)” and click Save.

Under the word “Expression” is where you will write the Arcade expression. By default, an example expression appears. This is a sample expression that you can delete when writing your own expressions, and shows an example of what  comments  look like in Arcade (denoted by the //). 

Step 2: Use an attribute from the layer to calculate a new value

First, let’s explore the expression window to better understand how to use it.

On the right side of the expression window, you’ll see the list of fields from your data, which are labeled as  Globals . They have $feature in front of the field name, which means that it will process the expression for each feature in the map. When working with Arcade within pop-ups, you’ll see additional  Globals  such as $map, which is used for  accessing data from other layers in map  using a function called  FeatureSet() .

Under the Functions tab, you’ll find a list of  built-in functions  that can be used to do things such as the  Proper()  function you saw in the example above. The documentation for each function is accessible through this window, making it easy to learn and use new functions.

When you want to reuse expressions you have already created on a layer, you can find them under the Existing tab. This will only appear once you have created an expression elsewhere.

The  Constants  tab contains formatting tools and other universal constants such as the value of pi.

To write our expression, we will use the left portion of the window. In the Globals tab, find the attribute field for Sea Surface Temperature (C). Click on the $feature.sst to add it to the expression. The attribute alias name appears above it as Field: Surface Temp (C)

Now, write out the equation for Celsius to Fahrenheit conversion we covered earlier. The * symbol can be used for multiplication, just as it in excel. The expression should look like this:

$feature.sst * 1.8 + 32

Step 3: Test and use

An easy way to make sure your expression works as expected is by testing it. The expression will return the last line of code, meaning if your expression is only one line, it will return the result of that line. If your expression is more advanced, you can use  a return statement  to control what the expression returns. Check out  examples from this blog  to see how return statements are used. Click the Test button, and a console will appear with the result of your expression. In this example, our result is a number, 81.4189998626709

This result is using a feature from the dataset to test. To see or change the value being tested, find the attribute in the list on the right and select the pencil to the far right. Our expression was tested on 27.454999923706055, which converted to Fahrenheit is in fact 81.4189998626709. This means that our expression is working as expected. Click OK to start using the expression.

Test with any value using the pencil next to the field

Now, we use our expression as if it’s a normal data attribute. In this case, we want to change the symbology to the Counts and Amounts (Color) option. 

Go into Options >> Symbols >> Fill and change the color ramp back to a bright red to replicate the map we started with. 

Move the transparency slider to 0%, click OK, click Done, and your map is now in Fahrenheit.

You did it! You wrote your first expression! If you’re feeling adventurous, use the same technique to use the expression you just wrote within the pop-up. You could also adjust the precision of the Fahrenheit value using the  Round()  function.

You can explore the map below and try your own edits by first clicking "Modify Map" at the top right.

What we've learned about Arcade

Arcade is a powerful way to save time and do on-the-fly calculations. This removes the need to own a data layer or perform field calculations to see immediate adjustments to your data values. Arcade simplifies the mapping process by giving us more control of the data. You no longer need to beg the owner of a layer to calculate a new field and hope it eventually happens. The freedom and time saved leaps us into more data exploration and less data wrangling.

There are many resources to help you be successful with your own Arcade expressions. Learn more here:

Story Map Tutorial:  How to Smart Map: Arcade 

Test with any value using the pencil next to the field