Members location mapping gadget

Using the members location mapping gadget, you can display an interactive map that shows where your members are located, and displays information about each member.

The process of setting up a members map involves setting up Google Maps integration, inserting a members location mapping gadget, then adjusting the members location mapping gadget settings.

For ideas and examples of ways to use this gadget, take a look at this blog post. 

To display member information in a table format, rather than on a map, you can insert a member directory gadget.

Billing for Google API usage

A Google billing account is required to access the Google APIs used by the members location mapping gadget. Depending on the number of times your member map is viewed, Google may charge the credit card associated with your Google account.

For each Google billing account, a credit of $200 USD is automatically applied. In other words, the first $200 of Google Maps API usage is free. 

Charges are approximately half a cent per transaction, so you'd need about 40,000 map requests before you use up your $200 credit and start getting billed.  

To avoid any charges beyond the credit limit, you can set your own API limits and alerts.

Wild Apricot does not charge anything for access to Google's Maps APIs. Any charges that you incur will be billed by Google to your Google billing account.

For more information on Google API billing, click here.

Setting up Google Maps integration

Before you can add the members location mapping gadget to a page on your site, you need to set up your Google Maps integration.

1. Go to the Google Cloud platform and click the Get Started button.
   
2. Create or sign into a Google account. You may be asked to enable billing for your account.
   For more information on Google billing accounts, click here. 
3. Create a new project or selecting an existing one.
   
4. After the API key is generated, do not click Done or copy the API key. Instead, click the Credentials page link.
   
5. Within the Application restrictions section, select the option to restrict this key's usage to HTTP referrers (websites).
   
6. Under Website restrictions, add your Wild Apricot domain name(s).
   You can enter the http or https version of your domain name, or both, with or without the www. Do not use the wildcard *.wildapricot.org. If you are using a custom domain name and want to see the map in admin view, add your wildapricot.org domain as well.
7. Click Save.
8. Copy the API key that appears. You'll need to paste it later in the field provided within your members location mapping gadget settings.
   
9. Click the Go to Google Maps Platform button.
10. Click the APIs option on the left.
    
11. Scroll down to the list of additional APIs and click Maps Javascript API.
    
12. Click the enable button to enable this API.
    

Now that your Google maps integration is set up, you can add the members location mapping gadget to a page on your Wild Apricot site. 

It may take up to 5 minutes for your settings to take effect. 

Adding a members location mapping gadget

To add a members location mapping gadget to a page on your site, follow these steps:

1. Click the Website menu, then click the Sites pages option within the Website module.
2. Create or begin editing the site page where you want the members map to appear.
3. Click the Gadget icon to display the list of available gadgets.
4. Drag the members location mapping gadget from the list, and drop it where you want it to appear on the page. You can insert it into a section within a layout, or above or below a layout.  
5. After you have dropped the gadget in the desired location, hover your pointer over it and click the Settings icon.
   
6. Within the gadget settings on the left, you need to paste the API key you copied above, then choose which members you want to display, choose the address field(s) that determine the location of your members, and decide which fields to display in the pop-up window for each member. For more information, see Gadget settings (below).
7. Click Save to save the changes to the page.

For instructions on restricting access to the page, see Page access and visibility. 

Gadget settings 

To complete the set up of your members location mapping gadget, you need to adjusts its gadget settings. Within the gadget settings, you need to paste the API key you copied above, then choose which members you want to display, choose the address field(s) that determine the location of your members, and decide which fields to display in the pop-up window for each member. There are also other optional settings you can adjust.

To display the settings for a gadget, hover over the gadget then click the Settings icon.

The following settings are available for members location mapping gadgets.

Members to include

Controls the kinds of members to be displayed on the map. Only members with a membership status of Active or Pending Renewal can be displayed. The following options are available:

All members
Include all members with a membership status of Active or Pending Renewal.

From saved search
Use a saved member search to limit members to those that match the saved search criteria. When you choose this option, you can choose from a list of your saved member searches. This option will only appear if you have a saved member search.

Selected levels
Restrict the map to members at selected membership levels. When you click this option, you can choose one or more membership levels. If you check the All levels option then all levels – including any levels added in the future – will be selected.   

Selected groups
Restrict the map to members belonging to selected member groups. When you click this option, you can choose one or more member groups. If you check the All groups option then all groups – including any groups added in the future – will be selected. 

Show bundle administrator only
Indicates whether to include only bundle administrators and exclude individual members of bundles.

Member address fields

To specify the location of your members, you can choose one or more address fields from your common fields and membership fields. At the very least, you need to choose one field that includes the country name. 

Make sure you only select geographic address fields (e.g. Address, State/Province, Country, Postal/Zip code). Selecting other types of fields may prevent your map from being displayed.

Don't choose admin only fields, or fields with access or privacy settings set to No access, and make sure that the members you chose to include are permitted to access the selected address field(s).

All common and membership fields are available for selection except system fields (such as first name, last name, email, phone, and organization), admin only fields, internal use fields, password fields, and fields that use the following field types: picture, date, extra charges, and rules and terms.

Pop-up window

You can choose up to 5 common or membership fields to be displayed in the pop-up window that appears for a member when you click their marker within the map. 

The first field you choose will be used as a link to each member's public profile.

Display map options

You can specify the height of the map in pixels.

Gadget title

If you specify a gadget title, the title will appear specially formatted within the gadget. Depending on the gadget style you choose, the title may appear in a heading box. If you want to add a description under the title, do not enter a gadget title, but instead, create a content gadget with a title and description, and place the content gadget ahead of this gadget.

For Kaleidoscope themes, use a Headline gadget instead of specifying a gadget title.

Gadget style

The gadget style determines the physical appearance of the gadget. The style you choose will determine the color and format of the gadget title, the gadget content, and the gadget border. You can choose from theme-specific styles and styles that are common to all themes. 

Margins

The amount of space – in pixels – that appears outside the gadget. You can set top, bottom, left, and right margins separately. 

Using the members map

While the gadget is loading the location information for your members, a notice will appear indicating its progress.

To refresh the gadget so that all processed markers are displayed, visitors can click the refresh icon within the notice.

When visitors to your site first view your map, the map is zoomed out to display all markers. Markers indicate the location of individual members. Multiple markers that appear in the same general area are represented by numbers that indicate the number of markers clustered together.

Visitors can click the number to zoom into that area. They can also enter a city, address, or postal code to jump to the specified location.

Visitors can click any of the markers to view a pop-up window displaying the member information you selected within the gadget settings.

They can also click the member's name to view the member's profile and send the member a message.

Setting API request limits and alerts

To avoid excessive charges for API usage, you can set your own smaller limits. Setting your own limits also protects you from someone stealing your API key and running up charges against your Google account. 

Wild Apricot is not responsible for the security of your Google Maps API key or for any charges to your Google billing account.

For instructions on setting API access limits, click here.

Limits can be set per day, per 100 seconds, or per 100 seconds per user.  We recommend the following daily limits:

• Dynamic maps - 5000 requests ($0.007 per each, $35 max) These are used each time the map is displayed
• Geocoding maps - 5000 requests ($0.005 per each, $25 max)
  These are used to retrieve the geolocation for each contact. This is performed once for each contact and doesn't depend on the number of times the map is displayed. Alternatively, you can set this to the number of members in your association.
• Autocomplete (per character) - 5000 requests ($0.00283 each, $14.5 max)
  This is used at least once when a visitor enters a search string in the map's search field.
• Places details - 1000 requests ($0.017 each, $17 max)
  This is used each time search is  performed within Google map

The total impact of these settings is a maximum charge of $92 a day, minus the $200 a month credit.

You can also set up alerts so that you are notified when your account charges reach a certain limit. You might want to set a limit of $200, since that's the amount of the free credit you receive each month. For instructions on setting billing alerts, click here.

Monitoring API request limits

You can monitor and manage your Geocoding API request limits from the Dashboard on your Google Cloud Platform Console.

For more information, see Google Cloud Billing Documentation.

Troubleshooting

One or more of my members are not appearing on the map

• Check their membership status. Only members with a membership status of Active or Pending Renewal can be displayed.
• Check their privacy settings for your location fields. If they are set to No access, then that member will not be displayed.
• Remember, it may take up to 5 minutes for your changes to take effect.

I'm seeing a "Something went wrong" error

• Check that you entered the URL correctly in the HTTP referrers section when setting up your Google Maps integration.
• Check to make sure that the Maps Javascript API is enabled on your Google Maps platform.

I'm seeing "Processing of markers is complete. Number of markers displayed: 0"

• Check to make sure that the Geocoding API is enabled on your Google Maps platform.