ArcGIS Online

Your Arcade Questions Answered

ArcGIS Arcade was introduced to the ArcGIS platform back in 2016 but is somewhat of a hidden gem. For those who have used it, there’s no secret that it is changing the way people make their maps and work with data. What is incredible, is that you don’t have to be a “coder” to do amazing things with Arcade. If you are, however, a coding wizard, Arcade is a powerful way to enhance your maps in new ways. 

regularly get questions about Arcade and what it can do. This made me realize that many people might have similar questions, so a ton of my Arcade wizard teammates and I compiled the most common questions we get about Arcade. While there are blogs, ArcGIS Learn resources, and documentation pages to get you started, not everyone has the time to spend on tutorials. In this article, my colleague Gee Fernando from Esri Australia and I offer easy-to-understand answers and examples to the questions we get the most. Feel free to use this resource if you are just getting started with Arcade, or if you are familiar with Arcade and have some nagging questions. You can also find the official ArcGIS Arcade FAQ here, which contains some of the same questions. 

Jump to a question:

What exactly is Arcade? 

ArcGIS Arcade is a scripting language that allows you to calculate new data values on-the-fly. Think of it like “calculate field” but without directly editing your database. What’s really cool about Arcade is that you don’t have to own a layer to do this. This makes it so that you can find layers from ArcGIS Online or ArcGIS Living Atlas and calculate and map completely new things! You also don’t need to be a “coder” to be able to create powerful calculations. It has a lot of similarities to Excel for basic functions, but also can be advanced similar to JavaScript for when you want to do more. 

Back to top of blog

Does Arcade change the underlying data table? 

Arcade allows you to calculate new values on-the-fly, meaning you aren’t actually writing anything to a table. This makes it easy to adjust and try out new things when working with spatial/tabular data. This is especially helpful when using layers that you don’t own yourself. However, if you own a layer, you can use Arcade to calculate a new field to your table if you want the result to be more permanent. 

Back to top of blog

Do I have to own a layer to use Arcade? 

Nope! This is one of the most powerful and understated parts of Arcade. You used to be stuck in the water if you found someone else’s layer but it didn’t have a field you wanted, or if a field wasn’t how you needed it. You’d have to contact the person and HOPE they update their service, or you’d need to find and host your own version of the data. Arcade empowers you to use data from trusted sources while still providing the freedom to customize or calculate your own things.  

Back to top of blog

Where do I find Arcade? How can I use it? 

You can write, share, and execute Arcade expressions in ArcGIS Online, ArcGIS Pro, ArcGIS API for JavaScript, and ArcGIS Runtime. The language is portable, meaning that an expression written in your web map popup will also work in your downstream apps like ArcGIS StoryMapsYou can find Arcade most places where you find and use other attributes. For example, symbology, labeling, transparency, popups, and more. The same way you would choose an attribute from your data to use for mapping/labeling/etc, you can choose to create an Arcade expression. Once you have created the expression, you will then find it in your attribute lists and can use it like any other field. Sometimes there’s a symbol that looks like a pencil (ArcGIS Online Map Viewer), an excel—like symbol (ArcGIS Pro), or you’ll find language about expressions (ArcGIS Online Map Viewer Beta). In this article, the example expressions you’ll see are built in the ArcGIS Online Map Viewer. 

Arcade has also recently been added into ArcGIS Dashboards Beta. Building an expression for a Dashboard will look slightly different, so to learn more about how to use Arcade in Dashboards, visit this informative blog by our colleague David Nyenhuis. 

Back to top of blog

What is an expression? What does it do? 

Expressions are just a fancy word for the script that you write. The map will treat this like any other data value from your map. Think of it like a new field for the features in your map. You can create many expressions and use them like you would any other attribute. The expression itself looks like a chunk of code, but can be as simple or complicated as you need.  

Do things as simple as adding 25 to a field value:

Or do more complex calculations:

Back to top of blog

I just opened the expression window. What am I seeing exactly? 

This window that appears is where you can create new values for the features in your map. The same way you calculate a new field, this window allows you to calculate new values by utilizing the other attributes in your layer, and even other layers in your map.  

The box on the left is where you write your expression. Whatever you tell this box to calculate, it will return that value for each feature in your map.  

Back to top of blog

What are globals? 

In the expression window you’ll see the word “Globals”. These are things in your map such as fieldsother layers (you’ll find those under $map), and other things. When looking at the globals list when working in symbology, you’ll see the list of fields. At the bottom, you’ll also see the map scale as $view.scale. This can be used to adjust the symbology by scale, like shown in this blogYou can also access the geometry of a feature by using $feature on its own. But we will address that in the next questionWhen looking at globals within popups, you’ll see more things appear in the list. The reason this list is different is because not all functions are supported in all places. This is mostly due to performance reasons. 

Back to top of blog

What is $feature?  

Think of $feature as just that… a feature on your map. When building an expression, $feature represents a single feature from the layer you are working with. Think of it as a row on your spatial table. You can access a particular field from that feature by using the “dot notation” or $feature.YOURFIELD. You’ll see this in the list of fields (Globals). You can also use brackets to access fields from a feature, with notation: $feature[‘YOURFIELD‘]. 

Back to top of blog

What do functions do? 

Like Excel, functions are built-in tools to help you process and clean your data. For example, the Round() function helps you round a value to the significant figures you want. So Round($feature[‘YOURFIELD’] ,1) would give you the value of each figure rounded to 1 decimal point. The help is also built straight into the window, so you don’t need to leave your map to learn more about a function and its syntax. Add a function into your expression with the syntax already built-in. Easy! You can also search for functions. 

Back to top of blog

Can I reuse an expression I’ve already written? 

Once you have created an expression within a layer in your web map, you can access that expression again when working on the same layer. The “Existing” tab that appears in ArcGIS Online allows you to choose an expression and it will auto populate into the expression window to easily reuse it. If you set an expression for your symbology and you want to reuse it in your popup, just go into the popup and find it within the Existing tab.

Back to top of blog

Where can I find examples of Arcade? 

There are many different places people have shared their Arcade to help others. Here are a few: 

Back to top of blog

My data changes behind-the-scenes regularly. Will my map show those changes if I use Arcade?  

Yes! The beauty of Arcade is that it is dynamic. Whenever you load a map, it will calculate the values from your expression on-the-fly. This means that changing data will adapt with no extra calculations or configuration on your part. When your layer has values that change regularly, your symbology/popup/etc. will all update automatically. For example, the Coral Reef Bleaching Dashboard in ArcGIS Living Atlas uses live feeds layer with data from NOAA that updates daily. The web map symbology and popup are driven by Arcade expressions, and the dashboard pulls in the web map. The web map and dashboard all update automatically when the data is updated, so the map stays current, even as real-life conditions change. 

Note: Your map will show the newest data values on its own, but your web map will use whatever symbology settings were set originally. New data could mean that you need to make accommodations to your symbology such as the breakpoints being used.

Back to top of blog

Can I create variables? 

AbsolutelyArcade is built on top of JavaScript, so the syntax for Arcade variables is very similar. You can declare a variable (var x) and assign it (=) to whatever you’d like. For example, this variable calls to my field “battery_level” and multiplies it by 10: 

Back to top of blog

I see something about “returns” in the documentation and examples. What does this mean exactly? Do I need to have one?

A return statement tells your expression what to return in the map. You can do a whole slew of loops and sub-calculations to get to your end goal, but the script will ultimately return whatever you tell it to using the word “return”. For example the previous question above shows us a statement where the expression will return the result of the calculation from the “battery” variable. However, you don’t always need a return statement. If you are doing a simple one-line expression, there is no need to add a return statement. You CAN add one, but it is not necessary. The example above will return the same thing if written like this: 

Back to top of blog

What’s the best way to debug an Arcade expression? 

There are two main tools to help you debug your expressions. The expression window has a button that says Test, and when that appears, you’ll see the Results panel. These are your weapons for success.  

The Results panel will tell you what the expression is trying to return in your map. If the type or resulting value isn’t what you expect, try investigating each line in your expression. Try using the return statement for each line along the way to make sure you are getting what you expect in each stepTo comment out any code, use // before anything you want the expression to ignore. 

You can also use the small pencil symbol to the right of a field to change the value being used in the test. By default it pulls the first record from your table, but if you want to test what the result will be for other scenarios, you can simply type in a different value.

Another way to see what the expression is returning at different points in your expression is by using the Console() function. This is almost like a print statement in other coding languages. See the documentation for a good example.

Back to top of blog

How do I write if/else logic? 

There are many ways to write if/else logic (conditional statements) in Arcade. Ultimately, I suggest doing what makes the most sense to you. If you are less comfortable with the syntax of Arcade, try using the IIF() or When() functions. First, you’ll need to know which operators to use when writing a statement. If you want to check if a variable x is greater than 25, your conditional statement will be simple: x > 25. If you want to check if that variable is greater than 25 and less than 100, your statement will need to combine those with the && operator: x > 25 && x <100. For the full list of operators in Arcade, you can find them near the bottom of this help page Here are a few ways to work with conditional statements in Arcade: 

Back to top of blog

Can I format text using Arcade? 

Yes! Arcade is a great way to make your pop-ups easier to read. Instead of raw data values, you can turn numbers into understandable and clean information. A few examples: 

These are just a few examples. There are also function like Replace(), and others that can grab the values you need from other fields in order to create new text values. Click here for the full list of text functions. 

Back to top of blog

Why isn’t the newline text formatting showing up on my labels?  

The TextFormatting.NewLine functionality is a great way to clean up your popups and labels but isn’t supported when labeling in the existing ArcGIS Online Map Viewer. Try viewing the map in the new Map Viewer Beta or adding the map into a 4.x supported app. To see which apps are 4.x, check out this blog. 

Back to top of blog

Is there a way I can handle null values in my popups? 

There are many different ways to handle null values in your data. Replace an awkward blank spot in your popup with a coherent phrase or placeholder. There are a few ways you can handle nulls, but some of the basics are by checking if a value is null using the IsEmpty() function, or by setting a DefaultValue()

Back to top of blog

How can I turn numeric values into categories? 

Using the technique mentioned in the earlier question about if/else statements, you can easily convert numeric values into categorical data. Write your conditional statement, and have the expression return the text you want to appear. The map will treat your result as text and map the results. For example, I want to show the battery level of Bird scooters around my area, but I want to easily recognize which ones need to be charged immediately. I can convert the battery_level field into different categories using the conditional statement techniques mentioned earlier: 

Back to top of blog

Can I convert field types using Arcade? 

How many times have you tried to map a field that LOOKS like a numeric field but it was actually a text field? You can create a new expression in order to use the field the way you need. 

You can use the Number() function to quickly convert it into a number. If you want to round that number, you can use the Round(function.

Similarly, if you want to show a numeric field as text, you can use the Text() function to do this. There is an example of this earlier in the article. 

Note: When using expressions in your map, you aren’t changing the field type on your table schema. If you own the layer and want to calculate a new field with the data type you want, you can do that directly within ArcGIS Online. Check out this blog to see how.

Back to top of blog

Can I do a unit conversion with Arcade? 

Absolutely! This is a great example of a simple calculation that can be done with Arcade. Simply use the attribute you want to convert and plug it into an equation. For example, if I have a map showing sea surface temperature in Celsius but I want to show the values in Fahrenheit, I can convert these using the equation CelsiusValue * 1.8 + 32. I can plug this straight into my expression calling to the sea surface field ($feature.sst). This story map shows step-by-step how to do a conversion like this. 

Back to top of blog

Can I work with date fields using Arcade?  

There are many Date functions available within Arcade. You can format these nicely for your popups and labels in order to communicate only the information you want the end-user to see. You can even calculate the difference between two dates, or determine how far away a date is from the current time by using the DateDiff() functionFor example, you can use this function along with the Now() function to figure out how recently something in your data was updated. You can then use text formatting methods to make it easy to read in your popup: 

You can also use the Text() function to give your date fields the look and feel that you want. For example, Text($feature.YOURDATEFIELD, ‘M/D/Y’) would return a string such as 7/4/2020 or  Text($feature.YOURDATEFIELD, ‘MM/DD/YY’) would return 07/04/20.

For a tutorial on how to work with date fields in Arcade, check out this blog by Gee Fernando. 

Back to top of blog

What is a FeatureSet?

FeatureSet() is a function that  allows you to access information from other layers in your map. FeatureSet is exactly what it sounds like. It is a set of features from within your map. So if you call to another layer in your map (or that SET of FEATURES), you will essentially be accessing that entire layer. Because of that, you can’t return a feature set directly, but rather you can work with that other layer to derive something from it. You can add a FeatureSet into your expression easily by going into $map, navigating to the layer you want to access information from, and clicking the FeatureSet button beneath it. This will add it directly into your expression. I usually set this feature set as a variable in order to easily access it later. You can see an example of how to add a FeatureSet to your expression in the question above called “what are globals?”.

You can use information from another layer from a FeatureSet in a few different ways: 

To learn more about these two methods, visit this blog for a detailed description and examples. This story map tutorial also provides instructions on how to make your layers talk to each other. 

But wait! You can also access information from other layers, even if the layers aren’t in your map! Instead of using the FeatueSet() function, you can use the FeatureSetByPortalItem() function. This function utilizes the item ID of a layer from so that it doesn’t have to clutter up your table of contents! This is described in detail in this blog. 

Note: Check out this blog for considerations when working with FeatureSets or think about calculating your field ahead of time using Arcade.

Back to top of blog

Can I work with related tables using Arcade?

You can work with related tables alot like the “attribute-driven” FeatureSets example described above. For an example, check out this blog by Gee Fernando for a step-by-step tutorial on how to do so.

Back to top of blog

Can I do spatial calculations in Arcade?   

Yes! One of the most powerful and hidden gems within Arcade is its ability to evaluate geometrical objects (AKA the features on your map). You can pass a feature from your map (literally as $feature), and the geometry function will perform an on-the-fly calculation based on your current map scale. For example, I can calculate the population density from the Living Atlas layer ACS Population Variables using the area of each feature along with the total population. Using many of the techniques seen in this article so far, we could use a calculation like this to create a simple formatted popup: 

Note #1: That this is not a replacement for advanced spatial analysis that you would do in ArcGIS Pro. There is a certain level of generalization that is done behind the scenes to your features in order to make the map performant. For more information about the context of geometry functions, please read the disclaimer in the documentation pages. 

Note #2: Geometry functions can be “expensive” calls, meaning they can be slow for advanced calculations. If you have millions of features or detailed polygons, consider using ArcGIS Pro geoprocessing or calculate the field value using Arcade. 

Back to top of blog

What is the difference between the intersects() and intersection() functions? 

Intersection() will give you the overlapping feature when comparing two geometries, like you would get using the Intersect tool in ArcGIS Pro. The Intersects() function, however, tells you if two geometries overlap. If you wanted to find if a point falls within a buffer, you would use the Intersects() function to provide a True/False statement (Boolean). But if you wanted to find the overlapping area of two polygons, you would use Intersection(). 

Back to top of blog

Can I list the closest locations to a point on my map?

We get this question pretty often, and the answer is yes! There are a few ways to do this. Using the Intersects() function mentioned above, along with the Buffer() or Distance() geometry functions, we can quickly see if two things fall within a range of each other. Using many of the techniques covered in this blog, we can use some advanced logic to find all overlapping features and list them out nicely in our popup. Below is an advanced example that compares recent earthquakes to the location of major cities. Using these two Living Atlas layers, the popup gives a formatted list of any earthquakes within 250km of a major city, or reports that no cities are nearby in order of their distance. I would recommend opening this map, clicking “Modify Map” at the top right, go into the layer settings to the popup configuration, and find the “Nearby Cities” expression. 

Note: as mentioned earlier, keep in mind that this call is happening client-side, so heavier requests can slow down your popup.

Back to top of blog

Why does my Arcade expression work in ArcGIS Online but not Web AppBuilder? 

As Arcade is implemented into different parts of the product, there can sometimes be slight differences in the version of Arcade. See the official answer to this question on the Arcade FAQs, and see the full matrix of Arcade versions throughout the ArcGIS product, visit this page 

Back to top of blog

More resources and tips: 

About the author

I am a Cartographic Product Engineer on the Living Atlas team at Esri. I work to create clear and concise stories about demographic data using cartography. I also build data layers and tutorials to help others create their own map masterpieces.

Connect:

Leave a Reply

Please Login to comment

Next Article

U.S. and Canada 2016 Demographic Maps to be Retired

Read this article