Displaying geographical data: Map widget

With a Map widget, users can search and view information for locations on a map on an iPhone, iPad, or Android device. You can specify the geographical location of each location on the map by either supplying the location as a spatial point, or by providing separate values for the longitude and latitude.

Locations on the map are displayed as map markers, bubble markers, color-coded areas, or points along a path displayed on the map. Tapping a location displays an Information Window with additional details about the selected location, as shown below:

You can display data in the Map widget in the following ways:

Display your data using static images as map markers. You can define a threshold on this metric to change the image used for the map markers. For information on defining thresholds on a metric, see the MicroStrategy Web Help.
Display your data using bubble markers. The size of each bubble marker is automatically determined based on the value of the metric on the columns of the widget. You can define a threshold on this metric to change the color of the bubble markers. For information on defining thresholds on a metric, see the MicroStrategy Web Help.
For iPhone and iPad documents, display your data as areas color-coded based on the population density of locations on the map. For example, you can display areas with a high concentration of stores in red, and areas with a low concentration of stores in blue.
Display your data as points on a path displayed on the map. The line used to represent the path is displayed as thicker for larger metric values and thinner for smaller metric values. For example, you can display ridership at different stops along a train route, with the most popular stations displayed with the thickest lines extending from the station.
For iPhone and iPad documents, color-code geographical regions, based on your data. For example, you can give each country displayed on a map a different color, based on their type of government. MicroStrategy provides maps with pre-defined regions, such as countries of the world or states in the US.
Create and format a custom Information Window, which is a pop-up window that displays additional data, for the Map widget. For steps to define an Information Window, see Providing additional information to users: Information Windows.
Filter the locations displayed on a Map widget to view only those locations that meet certain criteria. For example, if store locations are displayed on the widget, you can limit the displayed stores to only those within a specified zip code. For more information on filtering by geographical location, see Using the Geo Location prompt in the Map widget.

For iPhone and iPad documents, once you create a Map widget, you can display lines that show relationships between locations on the map. For steps to use lines for relationships, see Using lines to display relationships between locations in a Map widget.

To display your data in the Map widget, you must provide geographical information for each location in the map using attributes or attribute forms. You can provide this data in the following ways:

During the import data process, you can define an attribute and assign it a geo role to identify what type of geographical information it contains. For example, you can create an attribute called City, which contains the names of multiple cities, then assign it the City geo role. Web automatically creates the City attribute with the attribute forms Latitude and Longitude, which contain the latitude and longitude of each city. You can then use the City attribute to provide latitude and longitude information for locations in the widget. Web automatically adds latitude and longitude information as attribute forms to data columns with the Country, State, Zip Code, City, or Location geo roles. You can also use attributes that have been assigned the Latitude or Longitude geo roles to provide geographical information as attributes, as described in the prerequisites below. For background information on importing data into MicroStrategy Web, including steps to assign a geo role to an attribute, see the MicroStrategy Web Help. For steps to assign a geo role to an attribute in Developer, see the Developer Help.
Your administrator can create attributes containing location data to support the Map widget. Steps to create location data are included in the Warehouse Structure for Your Logical Data Model chapter in the Project Design Help.

Creating a Map widget

Prerequisites

The Grid/Graph for the Map widget must meet the following requirements:

Place the attribute or attributes containing the geographical information on the rows. The attributes must provide this information in one of three ways:

If you want to display geographical regions on the map, you must provide an attribute whose values match the names of regions in a map provided by MicroStrategy. You select the map you want to use in the steps below.

For example, MicroStrategy provides a map called Countries of the World. To display a map that contains a colored area for each country in which your company has sales representatives, you can create an attribute called Country, which contains the names of these countries, then use the Country attribute to provide location information in a widget that uses the Countries of the World map.

To provide the geographical information using attributes, you must provide one of the following:

One attribute that contains the latitude of each location and one attribute that contains the longitude of each location. For example, you can provide an attribute that has been assigned the Latitude geo role and an attribute that has been assigned the Longitude geo role.
One attribute that provides geographical information for each location as a point.

To provide the geographical information using attribute forms, you must provide one of the following:

One attribute, which provides the latitude and longitude of each location using separate attribute forms. For example, you can provide an attribute that has been assigned the Country, State, Zip Code, City, or Location geo roles.
One attribute that provides geographical information for each location as a point, using a single attribute form.

If you are using attribute forms, be sure that the attribute forms containing the geographical information are visible in the grid. Right-click the header of the attribute, point to Attribute Forms, then select the attribute forms you want to display.

Place at least one metric on the columns. You can define a threshold on this metric to change the display of markers on the map. For more information on thresholds, see the MicroStrategy Web Help.

You can add objects from multiple datasets to the Grid/Graph containing the widget. You must have the correct privileges and the project must allow Grid/Graphs to use multiple datasets. For steps to allow Grid/Graphs to use multiple datasets, see the Adding Text and Data chapter of the Document Creation Help.

To create and add a Map widget to a document for mobile devices

In MicroStrategy Web, open the document in Design or Editable Mode.
Go to Insert > Widgets > Mobile > Map.
Click the location on your document where you want to place the widget. The Grid/Graph containing the widget is displayed.
Optionally, resize the widget by clicking and then dragging its handles.
From the Dataset Objects panel on the left, select attributes and metrics, and drag them on to the Grid/Graph, as described in the prerequisites above.

Configure the widget's display properties

Right-click the widget, then select Properties and Formatting. The Properties and Formatting dialog box opens.
From the left, select Widget.
On the right, ensure that the check boxes for the mobile devices you are designing for are enabled, as applicable.
Click the Widget Properties icon . The Map Properties dialog box opens.
You can replace map markers with static images, bubble markers, color-coded areas based on the population density of locations on the map, or geographical regions. Do one of the following:

To use map markers to mark locations on the map, select the Use Image Markers option. From the drop-down list, select the marker image to use to display locations on the map. A preview of the selected marker style is displayed to the right of the drop-down list.
To use bubble markers to mark locations on the map, select the Use Bubble Markers option. The size of each bubble marker is automatically determined based on the value of the metric on the columns of the widget.
To use shades of color to indicate the concentration of locations on the map, select the Use Density Maps option. From the drop-down list, select the color theme to use to automatically color areas on the map. A preview of the selected color theme is displayed to the right of the drop-down list.
To display locations on the map as points on a path, select the Use as a Path on the Map option. From the drop-down list, select the color of the line to use to display the map path.
To display geographical regions on the map, select the Show Areas option. From the drop-down list, select the regions you want to use in the map.

You can determine how to size bubble markers representing negative metric values. From the Negative Values are Represented As drop-down list, select one of the following:

To use the absolute value of the metric to size the bubble marker, select Absolute Numbers. For example, a bubble representing a metric value of -2,500 will be displayed as the same size as a bubble representing 2,500.
To display bubble markers representing negative metric values as bubbles with a size of 7 pixels, select Bubbles Sized at 7 Pixels.

You can determine whether to apply threshold formatting to image markers or bubble markers in the widget. Do one of the following:

To enable threshold display, select the Apply threshold for the map check box.
To disable threshold display, clear the Apply threshold for the map check box.

You can choose to provide geographical information for the widget using attributes or attribute forms. From the Use Attribute or Form drop-down list, select one of the following:

To provide geographical information using attributes, select Use Attribute.
To provide geographical information using attribute forms, select Use Attribute Form.

You can determine whether to provide geographical information to the widget as a point, or as separate latitude and longitude values. Do one of the following:

To define the location as a point:

From the Select Data Type drop-down list, select the Point option.
If the Use Attribute or Form drop-down list is set to Use Attribute Form, from the Select Attribute drop-down list, select the attribute that contains the attribute form you want to use to display the widget.
From the Select Point drop-down list, select the attribute or attribute form that contains the point information.

To define the location as a latitude and longitude:

From the Select Data Type drop-down list, select the Latitude/Longitude option.
If the Use Attribute or Form drop-down list is set to Use Attribute Form, from the Select Attribute drop-down list, select the attribute that contains the attribute forms you want to use to display the widget.
From the Select Latitude drop-down list, select the attribute or attribute form that contains the latitude information.
From the Select Longitude drop-down list, select the attribute or attribute form that contains the longitude information.

From the Selection Display Attribute/Form drop-down list, select the attribute to use to display data in the Information Window when the user selects locations in the widget.
By default, if multiple locations in the widget have the same latitude and longitude—for example, two stores located in the same building—a separate map marker is displayed for each location. If you are designing this widget to be displayed on an iPhone or iPad, you can choose to display a separate map marker for each store, or display a single map marker for all of the stores at that location. Do one of the following:

To display a single map marker, select the For repeated rows, display only one marker for same location check box. When the user taps the map marker on the document, information for each location at the selected latitude and longitude is displayed. If map markers in the widget are displayed as bubble markers and a group of locations are located at the same latitude and longitude, the bubble marker for this group is sized and colored based on the last location in the group, as displayed in the widget. If subtotals are displayed in the widget, the subtotal for the group is used to size and color the bubble marker.
To display a separate map marker for each location, clear the For repeated rows, display only one marker for same location check box.

On a mobile device, tapping a map marker on the map displays additional information about the location in an Information Window.

You can define a layout in the document to use as a custom Information Window, and format its appearance. Select the Display Information Window from document layout check box. For instructions to configure the layout to use as the Information Window, see To specify a layout as an Information Window in a Map widget.

If you are designing the document for both iOS and Android devices, it is recommended that you use a panel stack as the Information Window. For detailed steps to define panel stacks as Information Windows, see Providing additional information to users: Information Windows.

From the Select Layout to use drop-down list, select the name of the layout to use as the Information Window.

You can specify the display theme to use to display the widget. For example, you can display the map as a satellite image, a map with topographical details, and so on. From the Default View drop-down list, select a display theme.
You can specify the type of magnification to apply to the map when the user selects a location in the widget. From the Redraw Behavior on Selector Action drop-down list, select one of the following:

To maintain the widget's current level of magnification, select Keep the Current Zoom.
To refit the contents of the widget to the selected area, select Refit the Content.

You can let users select areas, zoom in and out of the widget, and so on using the map toolbar. Under Map Elements Visibility Options, choose from the following:

To display the map toolbar at the top of the widget, select the Map toolbar check box. This option is selected by default.
To allow the user to select which display theme to use to display the map, select the Map view options check box. This option is selected by default.
To display a slider that allows the user to zoom in and out of the map, select the Zoom bar (Web only) check box. This option is selected by default.
To allow the user to view a list of the areas he has selected in the widget, select the Selection list bucket (Mobile only) check box. This option is selected by default.
To display the Current Location icon, which allows MicroStrategy to access an iPad user's current location, select the Current location (Mobile only) check box. If this option is selected, the icon is displayed even if the document does not have a Geo Location prompt. This option is cleared by default.

Complete the widget

The plus sign (+) at the top of the interface allows you to add additional datasets to the Map widget for display in MicroStrategy Web. For steps to add additional datasets for Web, see the GIS Integration Help.

Click OK to return to the Properties and Formatting dialog box.
Click OK again to save changes.

Using a layout as an Information Window in a Map widget

When a user taps a map marker in a Map widget on an iPhone, iPad, or Android device, a pop-up window is displayed. This Information Window provides additional details about the location, such as the location name and related metric values, as shown below:

Information Windows are automatically displayed for all markers, using a default layout and format. You can create and format a custom Information Window to display for a Map widget. To define a custom Information Window, you create a document layout, using either Developer or Web. You then enable the layout to be displayed as an Information Window and specify the layout as the Information Window in the Map widget's properties. Layouts enabled as an Information Window are not displayed with the other layouts in a document and are only displayed on mobile devices.

If you define an Information Window in a separate document, you can reuse the Information Window layout by importing it into other documents. For instructions on importing layouts, see the Document Creation Help.

Prerequisite

This procedure assumes you have already added a Map widget to the document. For instructions, see To create and add a Map widget to a document for mobile devices.

To specify a layout as an Information Window in a Map widget

In MicroStrategy Web, open the document that contains the Map widget in Design Mode.

Create the layout to use as the Information Window

Choose Insert > Layout. The Insert Layout dialog box opens.
Do one of the following to define a style for the new layout:

To define a layout style, click the Layout tab, then select a layout style.
To import a layout from a saved document, click the Document tab, then select a previously saved document.

Click OK. The new layout is displayed.

Add content to the layout

The content that you add to this layout is displayed in the Information Window. You can add any controls to the layout, including text fields, Grid/Graphs, images, shapes, and so on. For instructions, about designing documents, see the Report Services Document Creation Guide.

The container that displays the Information Window on the iPhone is 1.5 inches wide. Its height is defined to fit to the content, with a maximum height of 1 inch.

Enable the layout to be displayed as an Information Window

From the Tools menu, select Document Properties. The Properties dialog box opens.
From the Layout Properties section on the left, select Mobile.
Select the Use as Information Window check box.
Click OK. The layout is enabled as an Information Window.

Specify the Information Window layout to be displayed in the Map widget's properties

Select the tab of the layout that contains the Map widget, then right-click the widget.
Select Properties and Formatting. The Properties and Formatting dialog box opens.
From the left, select Widget.
Click the Widget Properties icon . The Map Properties dialog box opens.
Select the Display Information Window from document layout check box.
From the Select Layout to use drop-down list, select the name of the layout to use as the Information Window.
Click OK to apply the changes.
Click OK to return to the document.

Using the Geo Location prompt in the Map widget

The Geo Location prompt lets users answer a prompt by using the device's current geographical location. In a Map widget, a Geo Location prompt is typically used to filter data in the widget. For example, you can choose to display only those map markers that are in your current state.

You cannot add a prompt directly to a document; you must define the prompt on the dataset reports used for the document. For more information on using prompts in documents, see the Document Creation Help.

You can create the Geo Location prompt to do the following:

To automatically use the device's current longitude and latitude to filter the widget's results, define value prompts with the display style set to Geo Location. You must define two value prompts, one for latitude and one for longitude. The prompts are then automatically answered and do not display in the interface.
To filter an attribute element list using the current geographical location, you can define an attribute element prompt with the display style set to Geo Location.

Geo Location prompts are defined in MicroStrategy Web. For instructions, see Prompting users for their location: Geo Location prompts.

Filtering data based on geographical distance from a mobile device

You can filter data in a report to display information based on the distance between a location on the report, and the current location of an iPhone, iPad, or Android device. For example, in the image below, a report displays a list of stores.

When the report is viewed on a mobile device, the user can choose to display only stores within a ten mile radius, as shown in the image below.

If the report is displayed as a Map widget, only map markers for stores within a ten mile radius are displayed, as shown below.

To filter data based on the distance from a point of interest to a mobile device, you must first create a metric to calculate this distance. The steps to create this metric are described below.

Once you have created the distance calculation metric, you can use it to filter data by creating a prompt or filter using the metric. For example, you can:

Create a prompt to allow users to display only data for locations within a specified radius of the mobile device.
Create a filter to automatically display data only for locations greater than a certain distance from the mobile device.
In a Map widget, display map markers only for locations within a specified radius.

Prerequisites

You must create an attribute with attribute forms containing the latitude and longitude of each location to use for the distance calculation. For example, the Store attribute in the example above has two attribute forms, Latitude and Longitude, which contain the latitude and longitude information for each store.
You must create two Geo Location prompts, one each for the latitude and longitude. The prompts must be created as value prompts, as described in Allowing users to filter data based on a single value: Value prompts.

To create a metric to calculate the distance between locations and a mobile device

In Developer, from the File menu, point to New, and then Metric. The New Metric dialog box opens.
Click OK to create a new metric. The Metric Editor opens.
In the Definition pane, type the formula of the metric you want to create. Use the syntax in the table following this procedure for the metric's definition.
Click Save and Close. The Save As dialog box opens.
In the Object name field, type the name of the new metric. Use the name provided in the table below.
Navigate to the location in which you want to save the new metric, then click Save. The new metric is created.
Repeat the appropriate steps above to create each of the metrics required to calculate the distance to each store.
Once you have created the distance calculation metric, Point_Distance, you can create any of the following prompts to use the metric:

A Metric Qualification prompt. You can add the prompt to a report to let users specify a distance radius for which to display data. For information on creating Metric Qualification prompts, see the MicroStrategy Web Help.
A Metric Set Qualification filter. You can add the filter to a report or to a dataset report in a document, to automatically filter the data using the current location of the mobile device.
A prompt or filter that will use the metric, added to a report displayed as a Map widget, or to the dataset report of a Map widget in a document. When the Map widget is displayed on a mobile device, only the map markers for locations within the specified distance from the mobile device are displayed.

Metric Name	Metric Definition
Location_Lat	`Max(AttributeName@LatitudeFormName)` Replace `AttributeName` with the name of the location attribute, and replace `LatitudeFormName` with the attribute form that contains the latitude information for each location. For example, for an attribute named Store with the attribute forms Latitude and Longitude, create a metric with the name `Location_Lat`, with the definition `Max(Store@Latitude)`.
Location_Long	`Max(AttributeName@LongitudeFormName)` Replace `AttributeName` with the name of the location attribute, and replace `LongitudeFormName` with the attribute form that contains the longitude information for each location. For example, for an attribute named Store with the attribute forms Latitude and Longitude, create a metric with the name `Location_Long`, with the definition `Max(Store@Longitude)`.
DeltaLat/2	`(Radians(([Location_Lat] - ?LatitudePromptName)) / 2)` Replace `LatitudePromptName` with the name of the value prompt for latitude. For example, if the value prompt is named `Latitude`, the definition is `(Radians(([Location_Lat] - ?Latitude)) / 2)`.
DeltaLong/2	`(Radians (([Location_Long] - ?LongitudePromptName))/2)` Replace `LongitudePromptName` with the name of the value prompt for longitude. For example, if the value prompt is named `Longitude`, the definition is `(Radians(([Location_Long] - ?Longitude)) / 2)`.
A	`((Sin([DeltaLat/2]) * Sin([DeltaLat/2])) + (((Cos(Radians(?Latitude)) * Cos(Radians([Location_Lat]))) * Sin([DeltaLong/2])) * Sin([DeltaLong/2])))`
C	`(2 * [Atan2](Sqrt((1-A)), Sqrt(A)))`
Point_Distance	`(3959 * C)` This value is based on the radius of the Earth, 3,959 miles or 6,371 km. To calculate the distance between the stores and the mobile device using a different unit of distance, replace 3959 with the radius of the Earth in the units you want to use to measure distance. For example, to calculate distance in kilometers, the metric definition is `(6371 * C)`.

Using lines to display relationships between locations in a Map widget

Once you create a Map widget for an iPhone or iPad, you can show relationships between locations on the map when the widget is displayed on the device. To do this, you display lines between the map markers. You can choose to display these lines using different thicknesses or colors depending on the relationship between locations.

Prerequisites

The procedure assumes that you have created a Map widget. For more information on the requirements for this widget, see Creating a Map widget.
If you provided the location of each map marker in the Map widget using attribute forms, the Latitude, Longitude, and ID attribute forms of the location attribute should be displayed in the Map widget.
If you provided the location of each map marker in the Map widget using attributes, you must include the lookup attribute on the Map widget.
You must create a Grid/Graph that is used to display lines in the widget. This Grid/Graph includes the metrics used to determine the color and thickness of lines between map markers, and attributes containing the IDs of the starting and ending locations of each line. The IDs provided must correspond to the IDs used to identify map marker locations in the Map widget. The steps to create this Grid/Graph are below.

To display lines between map markers in a Map widget

Open the document in Design or Editable Mode.

To create the Grid/Graph for the relationships

From the Insert menu, select Grid/Graph.
Click the location on your document in which you want to place the Grid/Graph. This Grid/Graph will not be visible when the widget is displayed on the device, and should be in the same document section as the Map widget.
From the Dataset Objects panel on the left, select attributes and metrics, and drag them on top of the Grid/Graph, as described below:

You must place two attributes on the rows of the Grid/Graph, which must provide the IDs of the starting and ending locations of each line in the widget. The IDs provided must correspond to the ID forms in the attribute used to identify map marker locations in the Map widget. Place the attributes as follows:

The first attribute is the lookup attribute for the widget. It must contain a single attribute form containing the ID of the starting location for each line.
The second attribute must be a single attribute form containing the ID of the ending location for each line.

Place at least one metric on the Grid/Graph's columns:

The first metric automatically determines the thickness of each line displayed in the widget, with thick lines representing large metric values. For example, if airports are displayed in the Map widget, and the lines represent flights between each airport, you can add the Passenger Count metric to the Grid/Graph. When the widget is displayed on a mobile device, the flights with the most passengers are displayed with thick lines, while flights with less passengers are displayed with thin lines.

To display each line using the same thickness, you can provide a metric with a constant value.

The second metric is used to determine the color of each line in the widget. By default, each line in the widget is displayed using the default color. You can override the default color by defining a threshold to change the font color of the metric values that meet the threshold condition. For information on creating thresholds, refer to the MicroStrategy Web Help.

If only one metric is placed on the columns, all lines will display using the default color.

The ID attribute form of each attribute must be displayed in the Grid/Graph you just created. If they are not displayed, for each attribute, right-click the header of the attribute, point to Attribute Forms, then select the attribute forms you want to display.
If you provided the location of each map marker in the Map widget using attributes, you must include the lookup attribute on the Grid/Graph that you just created to display lines between the map markers. Place the lookup attribute on the rows of the Grid/Graph, directly before or directly after the attributes providing the latitude and longitude of each map marker.

To enable the line display

Right-click the Map widget, then select Properties and Formatting. The Properties and Formatting dialog box opens.
From the left, click Advanced.
Clear the Enable incremental fetch on grid check box, and click Apply.
From the left, select Widget.
Click the Widget Properties icon . The Map Properties dialog box opens.
To enable the display of lines, select the Display Affinity Lines/Arcs check box.
If the Use Attribute or Form option is set to Use Attribute, from the Select Lookup Attribute drop-down list, select the lookup attribute.
From the Select Affinity Data drop-down list, select the Grid/Graph that you created above.
From the Draw Arcs/Lines drop-down list, select Arcs to display curved lines or Lines to display straight lines.
From the Max Line Thickness drop-down list, select the maximum thickness that can be used to display lines in the widget. The thickness of each line is automatically determined based on the value of the first metric on the new Grid/Graph's rows. The default value is 5.
Click OK to return to the Properties and Formatting dialog box.
Click OK to save changes and return to the document.