Google Maps

The Logi Info Google Map element allows you to include the geo-mapping features of the Google Maps web service in your reports and you can combine it with your data to produce data-driven maps. This topic introduces the Google Maps web service and the Google Map element.

Logi Info also supports Leaflet Maps. For more information, see Leaflet Maps.

About Google Maps

As mentioned above, a Google Map is an interactive map that can use your data to identify locations and provide other features. The concept is simple: take two different data sources (your data and Google's maps) and combine them into a data-driven map.
 

        

The example above shows a Google Map of the area surrounding Washington, D.C. It's a typical map depicting roads, major land features, and significant points-of-interest. The example also identifies the available optional controls, the scale for indicating map distances, and the cursor shaped that appears when dragging the map within its viewing area.
 

The example above shows the same map with the Terrain map type selected.
 

This basic example shows the same map with the Satellite map type selected.
  

In Street View mode, Google Maps provide a street-level photographic view of a map area. Street View is engaged by dragging the "Peg Man" icon, as shown above, onto an enabled street (shown in blue when the icon is moved). Once dropped, the view switches to street-level and controls are presented allowing you to navigate and turn within the "virtual world".
 

Now the basic map example above includes a "mashup" of data. When identifying data is fed to the web service, the resulting output can pinpoint locations on the map. The example above shows how a geographic Map Marker is placed on the map to identify a specific location. Map Markers can use the default icon (shown) or a custom image, gauge, or even a chart. Optionally, the map can be configured to display a Map MarkerInfo window, containing additional location-specific data, when the marker is clicked.


     

The example shown above includes data-driven, colored regions (in this case, representing postal codes), known as Map Polygons, overlaid on a map of Washington, DC. Logi Info can work with GIS boundary data to produce region overlays for states, counties, cities, school districts, and other areas. Like the Map Marker, regions can be clicked to display a pop-up information window with detail data. They're discussed in more detail in Map Polygons.

Similarly, Map Polylines can be plotted from data to show a route, in this case from the Orsay Museum in Paris to the Louvre Museum. Polyline color, width, and transparency level are all configurable and can be set from data values. For more information, see Google Map Polylines.

 Google Maps can be exported to PDF. Prior to this version, they could not be exported to PDF. Google Maps cannot be exported to other formats, such as Word and Excel.

Back to top

What's a "Web Service"?

The formal definition of a web service is "a software system designed to support interoperable, machine-to-machine interaction over a network". In plain terms, developers can think of a web service as a standard programming "function" that happens to be hosted on an external machine, one that your Logi app reaches over the Internet. You send it parameters and the web service sends you results, with the benefit that the whole process is language neutral.


     

The diagram above illustrates how this fits into the Logi application architecture. Usually, the "parameters" that you send to the web service come from a database that your application queries. The results are used in the HTML pages that are output to a browser. Logi Studio elements make the process of connecting to, and communicating with, the web service very easy.

Back to top

Getting a Google Maps API Key

In order to use the Google Map elements in your application, you'll need a Google API key. Logi Info uses Google's Maps JavaScript API version 3.

In July 2018, Google changed its licensing scheme, ending the free API access previously offered at some usage levels. This specifically affected geocoding in Logi applications.

Logi Info now includes the Connection.Nominatim element, for connections to a free, public, OpenStreetMap (OSM) Nominatim server for geographic data. Using a simple REST API, geocoding results are returned as XML or JSON data. For more information, see Introducing Datasource Connections.  

Information about how to get a Google Maps JavaScript API key is available in Google Connections. Please read that topic and take the necessary steps before proceeding to implement Google Map in your Logi application.

Back to top

The Google Map Family of Elements

A number of Logi Studio elements make up the family used to create Google Maps. Each element, its function, and its attributes are discussed below:
 

Connection.Google Maps - This special type of Connection element is required for communicating with the web service. Like all Connection elements, it resides in your _Settings definition.

See Google Connections for detailed information about getting an API Key and configuring this element.

Google Map - The root element for implementing a Google Map in your report. Attributes include:

  • ID - (Required) A unique ID for this element.
  • Height & Width - (Required) The dimensions, in pixels, of the map.
  • Connection ID - The ID of the Connection.Google Maps element you added to your _Settings definition. If blank, the first (top-most) element of this type in _Settings will be used by default.
  • Google Map Show Traffic- Specifies whether or not vehicular traffic information will appear on the map. Default value: False
  • Google Map Street View - Specifies whether or not the "Street View" control appears on the map. This control contains a "peg man" icon that can be dragged onto the map to enable Street View mode, which provides a street-level photographic view of the surroundings of the icon. Default value: True
  • Google Map Type Control - Specifies whether or not the Map Type controls appear on the map. These controls allow the user to select the type of map to be shown ("Map", "Satellite", etc.). The available map types the user can select will vary depending on the map size and the value of the Google Map Types attribute. The default value is Auto, which selects the best control types based on map size and other factors.
  • Google Map Types - Specifies the type of map available for selection by the user when Google Map Type Control value is True or Auto. One or more map types may be entered, separated by commas, making the corresponding map types available to the user. The first map type entered will be the default type shown when the map is first displayed. Available map type values include Map, Hybrid, Satellite, Traffic, and Terrain.
  • Google Map Zoom Control - Specifies whether a zoom control appears on the map.  The default is True.
  • Map Scale - Specifies whether a scale legend appears on the map. Default value: False
  • Security Right ID - When Logi Security is enabled, specifies the Security Right IDs of users who will be able to see this element. Multiple Right IDs, separated by commas may be entered.

Map Initial View - Allows you to optionally set the initial Zoom Level and geographic location the map will open to when the page is first displayed. Attributes include:

  • Map Zoom Level - Specifies the resolution of the initial map. Values can range from 0 (the lowest zoom level, in which the entire world appears on one map) to 21+ (down to individual buildings).
  • Latitude & Longitude - Specifies the positioning values, in the data returned in the associated datalayer, for each marker. If left blank, the defaults are "@Data.Latitude~" and "@Data.Longitude~". Like all tokens, the column names are case-sensitive.

Map Markers - Map Markers appear on the map to pinpoint a location, based on latitude and longitude positioning values. The graphic image for the marker can consist of an image, chart, or gauge; a default image is provided. Attributes include:

  • ID - (Required) A unique ID for this element.
  • Latitude & Longitude - Specifies the positioning values, in the data returned in the associated datalayer, for each marker. If left blank, the defaults are "@Data.Latitude~" and "@Data.Longitude~". Like all tokens, the column names are case-sensitive.
  • Security Right ID - When Logi Security is enabled, specifies the Security Right IDs of users who will be able to see the markers. Multiple Right IDs, separated by commas may be entered.

You can add Action elements below this element so that when a user clicks a marker, an information panel appears or another report is shown.
 

Map Marker Image - This optional element is a container for one Image, Gauge, or Chart element that provides the image for the Map Marker element. If this element is not included in the definition, the default marker image is used. The default image is:

     

Data can be used here in interesting ways. For example, an image caption (image file name) and the image size can be data from the datalayer (their values can be @Data tokens), so locations can be differentiated visually based on their data.

The marker image can also be an actual gauge or chart which would also immediately differentiate locations based on their data.

Map Marker Label - This optional element allows you to define a label that will appear under the marker. The label can be styled most easily by defining a CSS class. Its attributes are Caption and Class.

Map Marker Clustering - When present, this optional element will group markers into clusters according to their distance from a cluster's center. When a marker is added, the marker cluster will find a position in all the clusters or, if it fails to find one, will create a new cluster with the marker. The number of markers in a cluster will be displayed on the cluster marker. Clusters will break apart into individual markers when the mapped is zoomed-in sufficiently. This element has no attributes.

Map Polygons - Map Polygons are regions plotted onto a map and are optional. They can be semi-transparent and have colors that are based on data values. Polygons are plotted from sets of latitude and longitude points. These typically come from a DataLayer.Gpx File or DataLayer.Kml File element.

  • ID - (Required) A unique ID for this element.
  • Border Color and Thickness - Specifies the polygon border color and thickness in pixels. Default color: Red
  • Border Transparency - Specifies a level of transparency for the border, where 0 = opaque and 15 = completely transparent. Default: 4
  • Fill Color - Specifies the color that fills the polygon interior. Tokens can be used here to set the color based on data. Default: Red
  • Fill Transparency - Specifies a level of transparency for the interior, where 0 = opaque and 15 = completely transparent. Default: 4

You can add Action elements below this element so that when a user clicks a polygon, an information panel appears or another report is shown.

Map Polylines - Map Polylines are lines plotted onto a map and are optional. They can be semi-transparent and have colors that are based on data values. Polylines are plotted from sets of latitude and longitude points. These typically come from a DataLayer.Gpx File or DataLayer.Kml File element.

  • ID - (Required) A unique ID for this element.
  • Border Color and Thickness - Specifies the polygon border color and thickness in pixels. Default color: Red
  • Border Transparency - Specifies a level of transparency for the border, where 0 = opaque and 15 = completely transparent. Default: 4

You can add Action elements below this element so that when a user clicks a polygon, an information panel appears or another report is shown.

KML Overlay - The KML Overlay element allows display of one or more KML files as overlays on the Google Map and is optional. When an overlay is used, the boundary viewport (location and zoom) are set according to the last KML file in the list.

  • ID - (Required) A unique ID for this element.
  • KML URL - The URL of a KML or KMZ file. The URL must be publicly-accessible; local intranet URLs will not work.

DataLayer Element - Datalayer elements are used as usual for any data retrieval operation and can have Group Filters, etc. as child elements to shape the data. Any type of datalayer element can be used.

The data for this purpose should include at least some combination of the following (see section About Mapping Data, below):

  • Street address
  • City
  • State
  • Postal Code
     

Geocode Columns - This optional element can be used if your data does not already include geographic coordinates. It accepts address data and, via the Google web service, attempts to retrieve latitude and longitude values ("geocoding") for each record in the datalayer. The values are placed into two columns, named "Longitude" and "Latitude", which are added to the datalayer data.

 You must either secure a Google Maps API license to use this element or use an alternate geographic data source.

Logi Info now includes the Connection.Nominatim element, for connections to a free, public, OpenStreetMap (OSM) Nominatim server for geographic data. For more information, see Introducing Datasource Connections.  

Follow this link for a list of the countries for which Google currently provides geocoding. Other web service brokers also provide geocoding in other countries. Element Attributes include:

  • City Data Column - Name of a datalayer column that has the city name.
  • Connection ID - The ID of the Connection.Google Maps element you added to your _Settings definition. If blank, the first (top-most) element of this type in _Settings will be used by default.
  • Country Data Column - Name of a datalayer column that has the country name.
  • ID - A unique ID for this element.
  • Include Condition - An expression that evaluates to a value of True or False. If the attribute is blank or evaluates to True, geocoding will occur; if the value evaluates to False, the element is skipped.
  • House Number Data Column - The name of a datalayer column that contains the street number.
  • Latitude Column ID & Longitude Column ID - The names of the columns that the web service will add to the datalayer and fill-in with the Latitude and Longitude values. Default column names are "Latitude" and "Longitude".
  • Place Data Column - The name of a datalayer column that has the entire address information or a place name in a single string. Use this attribute when the address data is not broken up into separate columns or when naming a point-of-interest, such as "Washington Monument" or "Grand Canyon". Use of this attribute disables the other location data columns.
  • Postal Code Data Column - The name of a datalayer column that has the postal code data (the "Zip Code" in the U.S.)
  • State Province Data Column - The name of a datalayer column that has the state or province name.
  • Street Data Column - Name of a datalayer column that contains the street name.

Reverse Geocode Columns - This optional element can be used to produce address data from geographic coordinates. Using the Google Maps web service, values returned are put into columns that are added to the datalayer, using these column names:

"StreetNumber", "StreetName", "Locality", "Sublocality", "AreaLevel1",
"AreaLevel2", "AreaLevel3", "Country", "Latitude", "Longitude", and  "PostalCode".

 You must secure a Google Maps API license key to use this element.

Logi Info now includes the Connection.Nominatim element, for connections to a free, public, OpenStreetMap (OSM) Nominatim server for geographic data. For more information, see Introducing Datasource Connections.  

Attributes include:

  • ID - (Required) A unique ID for this element.
  • Latitude Data Column - (Required) Name of the existing datalayer column that contains the latitude data.
  • Longitude Data Column - (Required) Name of the existing datalayer column that contains the longitude data.

Action.Map Marker Info - This optional element adds click event processing to the Map Markers element. When a map marker is clicked, processing flow continues with this element's child elements. Attributes are:

  • ID - (Required) A unique ID for this element.
  • Security Right ID - Specifies which security rights can click the map and invoke an action. If blank, then access is unrestricted.

Map Marker Info - This optional element represents the pop-up "balloon" that appears over the map when the parent Map Marker is clicked. A wide variety of elements, forming a virtual sub-report, can be placed as children below this element. These can include images, charts, links, data, and more. The data from the row associated with the clicked marker is available to the children of this element. (see the example image below).

Refreshing Google Maps

Developers may want to refresh their Google Maps with new data, either automatically or in response to user input. To do this, you can, of course, use an Action.Report element to refresh the entire report page.

Use a SubReport

If you just want to refresh the map, not the entire page, you can place your Google Map in a separate report definition and then include it in your original report as a subreport using the SubReport element:
 

Make the SubReport element the target of an Action.Refresh Element or Refresh Element Timer element, as shown above. Use Link Parameters under the Action element to pass any necessary values to the Google Map. This is the recommended method of updating Google Maps in Dashboard panels.

A Google Map element cannot be the direct target of an Action.Refresh Element or Refresh Element Timer element; not even if you wrap the map in a Division. This is why using a SubReport is recommended.

A Google Map element can now be the direct target of an Action.Refresh Element or Refresh Element Timer element, however, this refreshes only the Map Markers and not the entire map.

Back to top

About Mapping Data

Data used for Google Maps typically contains, at the least, address information. When this information is sent to the web service, the map generated will be scaled to fit the data into the dimensions you set for the map (in the Google Map element).

        
     

For example, if your data only includes state/province information for a single state, the map generated will be scaled to show as much of the state as necessary to include all of the map markers (above, left). This could be the result, for example, of a SQL query statement that includes a WHERE State = 'MT' clause.

However, if your data includes street address, city, and state/province information, the map generated will be scaled as a street-level map (above, right). This could be the result, for example, of a SQL query statement that includes a WHERE City = 'New York' clause.


     

As shown above, one of the benefits of the interactive nature of these maps is that you can display additional information when the map marker is clicked. So, your data might include business intelligence data in addition to the address information.

For example, revenue figures or employee counts. This data can be displayed, as in the example, in the Info Window that pops up when a marker is clicked. The Info Window can also contain images, charts, gauges, sub-reports, and links, all driven by data.

 If your data already includes latitude and longitude positioning data, so much the better. The use of Geocode Column elements to provide that data involves making additional network "trips" to the web service and that could mean additional transaction fees. Google imposes geocoding limits based on your license type; enterprise users may have other contractual limits. See this Google Maps Geocoding Usage Billing page for more information about prices and limits.

Logi Info now includes the Connection.Nominatim element, for connections to a free, public, OpenStreetMap (OSM) Nominatim server for geographic data. For more information, see Introducing Datasource Connections.

Support for data that includes "MultiGeometry" tags is included.

This concludes this introduction to Google Maps. For additional information, see Google Map Tutorial.

With special thanks to contributing writer Michael Kujawski.

Back to top