Setup¶

Step 1

Create a Google Cloud account, if you do not already have one by clicking here.

You can view their pricing details here.

Note

Google gives each account a $200 monthly credit for their API usage, making it likely that your costs will be minimal or null. This credit equates to roughly 40k free geocodes per month. This is dependent on other uses of the APIs including but not limited to mapping.

From that same pricing page, you can initiate the creation of your account by clicking on the Get Started button in the upper, right corner. When you are prompted to select the products you want, select both Maps and Places and continue with the account setup.

Choose both Maps and Places

Create API Keys

After completing the account creation, you will need to create and configure two API keys. First, double-check to make sure the needed services are enabled. Go to your new account console. If necessary, open the navigation panel on the left by clicking on the hamburger icon (the triple horizontal lines). Then go to APIs & Services > Library and ensure the Geocoding API is enabled.

Next, create an API key at APIs & Services > Credentials. (One key may have already been created for you at account initialization.) Give the keys the following name and restrictions:

1. touchpoint-gmap

   This API will be used for the map display. Under Application Restrictions, select HTTP Referrers (web sites) and enter your database URL followed by /*. For example, https://bellevue.tpsdb.com/*. If you have a custom domain, you will need to add it also, using the same format. For example, https://my.bellevue.org/*. Under API Restrictions, select Restrict Key and select Maps JavaScript API.

2. touchpoint-geocode

   This will be used for the backend geocoding call to pull latitude and longitude. Under Application Restrictions, leave the setting as None. Under API Restrictions, select Restrict Key and select Geocoding API.

Navigate to Administration > Settings > Features > Small Group Finder & Family Map. For the Google Maps API Key setting, enter the value of the key named touchpoint-gmap. (Make sure you copy the key itself, not the name.).

For the Google Geocode API Key setting, enter the value of the key named touchpoint-geocode. (As above, make sure you copy the key itself, not the name.)

Step 2

Toggle the Enable Nightly Geocoding setting to True and set the Max Geocoded Addresses Per Day. This setting is helpful if you want to limit your usage (and costs) of the Google Geocode API key.

Note

If no max is set, the default is 1000 addresses. If you are just starting, you might want to set this higher until all your addresses are coded, and then set it to a lower amount moving forward.

Step 3

Visit this website to create your map and define the geographic regions. You can define your regions by creating a custom Google map, adding layers, and using the “add line or shape” tool. We recommend designating one person from the church to create and update your map.

Sample Map With Geo-Regions

Step 4

Once your map is created, use the option to “Export to KML” to get a file that can then be uploaded by navigating to Admin > Batch Actions > Geocoding.

When you upload the file, it will automatically set the available Geo-Regions for your database and assign that region to any record whose address falls within that region.

This page will give you a quick summary of the following:

• Addresses With Geocodes - These are addresses that already have a latitude and longitude point (i.e. geocode) set.

• Addresses With Regions - Of the addresses that have a geocode, these are the ones that fall within a defined region that you have set up.

• Addresses Without Geocodes - These are the addresses that have yet to be coded (these are coded each night as part of the nightly batch service).

• People Without Addresses - These are the people that don’t have addresses and therefore cannot be geocoded.

Feature Use¶

Here are some examples of ways to use this feature.

Identify Geo-Region On A People Record¶

Once a People Record has been updated (occurring nightly as described above in Step 2), the record will have a Geo-Region assigned to it, visible by clicking on the Pencil Icon next to the address. The Geo-Region is set and updated nightly.

Use Search Builder To Identify Those Within a Geo-Region¶

Navigate to People > Search Builder > New and select the Search Builder Condition Geographic Region. Keep the Comparison set to Equal and select the Region from the items available in the Codes list.

Run Report To See Families On A Map¶

From Search Builder, navigate to the Cloud Icon on the Blue Toolbar and select Family Map, found under Directories.

This will generate a map with colored pin heads (representing the families within the search results) corresponding to the Geographic Regions set on your map (defined above in Step 2). Once clicked, each pin head will also reveal the Family Name and ID.

Latest Update

8/29/2022

Clarified steps