Map Elements

What You'll Learn

In this guide, you'll discover how to implement Map Elements to give your app powerful location-based visualization capabilities. You'll learn how to configure maps to display your data points, customize their appearance with different pin colors, implement search functionality, and present additional information about each location. By mastering Map Elements, you'll enhance your app with intuitive geographic interfaces that help users quickly find what they're looking for based on location.

What are Map Elements?

A Map Element displays records from your database on a map in your Live App. The system uses maps to display geocoded address field values.

You have the option to use Google as your map provider by adding your API key. This setting can be found on the Settings > App Settings > Map Provider page.

Note: As of 2024-01-29, any apps that are using Google Maps as the map provider will require a Map ID to be entered in the App Settings > Map Provider section of the Builder. See Google's documentation on creating a Map ID here.

General Notes About Map Elements

• The Map Element is currently only available on the Trial, and Pro plan and above.
• Maps can only display tables that have an address field. This address field will be geolocated and will determine which records the map will display.
• When using the latitude/longitude coordinates option for an address field, that location will display as the nearest street address on a map element, rather than the exact coordinates.
• Map elements will automatically generate direction links that, when clicked, will open a new window for Google Maps where the user can get directions.
• Address fields used in map elements where the address autocomplete functionality is enabled will allow this autocomplete functionality in the search input.

What do Maps Look Like in the Live App?

Maps display multiple records from one of the tables in your database:

On the search results display, a "reset" link will appear. Clicking this will reset all search criteria to easily search again with new criteria.

Instead of using our default map feature, you can also choose to use Google Maps by entering your API key. See the section above for more details on this.

Managing Maps

To learn how to add, edit, and delete map elements from your app, see our Elements Overview article.

Map Settings

To access the settings of a map element, hover your mouse over the element and click on the pencil icon that appears at the top left of the element.

Source

The Source section is used to control the records the map will display:

In this section, the following options are available:

• Filters: The map will display all the table's records by default. Use the Data section to add rules to limit which records will be displayed.

• Limit: Show all the available records or limit the shown records to a specific number.

Note: Currently, map elements can only show 1,000 records at a time.

Tip: To learn more on working with the element's source, see our Element Source Settings article.

Map Options and Settings

The Map Settings section is used to control how the map works with your table to display addresses:

Here is the list of customization settings available from the map's options and settings section:

• Address Field: Select a field that the map will use as the address to place each location on the map. This field must be the Address type.

Note: New maps will use the first address field to display records in the map as well as the first short text field as a label when displaying address details.

• Title Field: Select a field the map will use to display an address point. Choose a title, name, or other field that can easily identify the whole record.

• Map Size: The dimensions of the map in pixels. Use these to control how big you want the map to be.

• List Width: This is for the width of the list that displays to the right of the map and contains the record details (see below). If the map and list width combined won't fit on the screen, then the list will bump below the map and be the same width as the map.

• Units: Select which unit of measuring distance will be used on the map: miles or kilometers.

• Starting Range: This is for the distance of the range to search by based on the selected unit (above). A record address must be within this distance of the searched address.

• Starting Point: Blank, Specific Address, or User's Current Location.

  • If Blank, then no records will show until the user initiates a search.
  • If an address is provided, then the map will start with records closest to that address.
  • When using the User's Current Location, the browser will ask the user's permission to locate them and use that location.

• Pin Colors: Add custom rules to display different pin colors based on criteria you define.

• Pagination: Pagination determines how many records will show at one time. If the total number of records exceeds the pagination number, then links will be added to the table to navigate all the pages. Options here include:

  • Set how many records to show at a time
  • Let the user set how many records to view per page
  • Show pagination controls at the bottom of the element

• Filters: Filters give the user tools to further refine which records the map will show. You can add filters as options for the user to add or as a menu.

  • User Filters: Enabling user filters presents options for a user to add any filters they'd like to the map. This will then display an "add filter" link above the map. The map will update as soon as a filter is added. Multiple filters can be added as needed. You can determine if the fields available to filter are limited to the map details or all the table's fields. You can add preset filters that will initially filter the records.
  • Filter Menu: Enabling a filter menu will present links above the map the user can click that will filter the records based on the rules you create.

Location Details

The Add Map Details (Location Details) section controls the list that displays to the right of the map with additional details about each record:

This list follows the same model as a details element.

Tip: To learn more about managing details, see our Detail Elements article.

Title and Description

In the Map Settings section of the element editor, you can customize the title and description of your map or leave them blank.

Here is what a map element looks like with no title or description:

Here is what a map element with a title and description looks like:

Searching with a Map

Maps currently support the below searches:

• Street address + city
• Street address + state
• Street address + city + state
• City + state
• State (resolves to the state capital)

Unsupported searches include:

• Street address only
• City only
• ZIP code only
• County only

How To Guides

There are several How-To Guides that involve using Map elements and our location features for capturing and displaying records:

• How to Add a Map to a Details Element
• How to Build a Map Directory or Store Locator App
• How to Automatically Capture a User's Location on a Form

Notes & Limitations

• Currently, for pagination on map elements, you can display a maximum of 100 records at a time.
• For the source settings, map elements can show a maximum of 1,000 records in total.
• Currently, there is no option to set maps to satellite view or terrain view.
• In the Builder and Live App, we are investigating an issue where address fields using address auto-complete and with the format of "International (with country)", are not populating the province/region field correctly for some addresses located in New Zealand, Australia, Belgium, Taiwan, and Spain.
• Address fields with lat/long format and geo-coding enabled may contain coordinates without a land address (e.g., ocean locations). These values are stored but not displayed in the UI. "Is blank" filter includes these fields. To view stored lat/long values, disable geo-coding.