Family Mapping ============== Family Mapping is a feature that allows you to set a latitude and longitude for every person's address in the database, which can then be used to find out which geographic region they live in (based on a map you define and upload to TouchPoint) as well as visualize where people live with points on a map. .. admonition:: Use Case Once this feature is configured and addresses are updating nightly, each person's address (that has been updated) will be automatically assigned a Geo-Region. The regions are configured by your church (instructions below). This will allow you to run reports based on the Geo-Regions to guide ministry decisions. For example, you can run a Search Builder search using the `Geographic Region` Condition (specifying a particular region in your area) and the `In Main Fellowship` Condition (set to `False`) to find those who live in that region but aren't involved in a Main Fellowship Involvement. This may help inform your decisions for starting a Small Group within a particular community. 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. .. figure:: https://i.tpsdb.com/EnableGoogleMapsPlatform.png :target: # 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. .. figure:: https://i.tpsdb.com/Hayley-GeocodingMap.png :target: # 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. .. figure:: https://i.tpsdb.com/Hayley-GeoRegions.png :target: # | 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. .. figure:: https://i.tpsdb.com/Hayley-GeoRegionsSB.png :target: # This screenshot is from a Training database. Your Geo-Regions will likely be neighborhoods or towns, not states. 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`. .. figure:: https://i.tpsdb.com/Hayley-GeocodingFamilyMap.png :target: # | 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