Geopointe

The Geocoder

Geocoding is the process of converting address data to latitude and longitude coordinates so that records can be placed on a map. The Geopointe geocoder runs in the background of Geopointe, processing this geographical data and monitoring for new and updated data. 

Ways to Run the Geocoder

Scheduled Job (Recommended)

To maintain accurate geocoding results, you need to schedule the geocoder. To do this, navigate to Geopointe Setup, click the Batch Jobs sub-tab, then click Schedule Geocoder. This has queued an Apex job in your system that will run hourly and geocode your data.

You can see that it has set the status of the job, it's frequency, and the time of the next scheduled run. Once it has run the first time, you will have Geocode data available to you under the Geocodes tab.

Batch

You can also run the geocoder manually from the Batch Geocode column of the Map Objects tab, as an alternative to the hourly schedule. If you choose All, the geocoder will re-evaluate all records for that object (needed rarely, typically for troubleshooting purposes). If you just want to run an update to process newly-added records, choose Delta.

Geocode Quality

The geocoder also returns a value to indicate its level of accuracy. You’ll want as many records to read ADDRESS as possible. The clean address will map in the system, but if the clean address doesn’t have enough data to map properly, the location will be incorrect.

Geopointe uses three colors to distinguish between the qualities, as indicated below:

  • Green: ROOFTOP – Good for maps and routing, the most precise result.
  • Yellow: RANGE_INTERPOLATED – Still fairly accurate at a street level. Interpolated results are between two precise points such as intersections. Interpolated results are generally returned when rooftop geocodes are unavailable for a street address.
  • Red: GEOMETRIC_CENTER, APPROXIMATE – Use caution with these values. They may be inaccurate or very generic in location such as the center of a city or postal code.

Latitude and Longitude

The geocoder also returns the latitude and longitude for each record. There are currently 3 sets of latitude and longitude fields. This duplication is due to legacy implementations and Salesforce constraints in the ability to remove them. 

All fields will contain the same values but using Latitude (search) and Longitude (search) is recommended, as these fields are indexed.

If the record uses customer-provided longitude and latitude values, the box next to Uses Customer Geocodes is checked.

Processing Speed

The geocoder runs very quickly and can process 1,000+ records per minute. Your data will be processed and ready to map soon after sending it to the geocoder.

In certain situations, some records may not be geocoded on the first run of the batch job. See the FAQ below for more information.

Geocode Cleanup Job

There are times when you need to delete unwanted geocode records. These are geocode records that are no longer attached to a parent record. This happens through map object edits, map object deletion, or parent record deletion. Orphaned geocode records are automatically deleted weekly, but you may want to get the extra records out faster. They are not visible to you, but can take up space until deleted. If you suspect orphaned geocode records are cluttering space on your Salesforce org, you can manually kick off the cleanup job by clicking Run Cleanup in the Batch Jobs sub-tab in Geopointe Setup.

The Geopointe Geocodes Tab

The Geopointe Geocodes tab stores  geocode data for every record that has been processed. If you don't see the tab, you can access it in Classic by clicking the + (All Tabs) or in Lightning under All Items in the App Manager. The geocode record detail page displays information such as the latitude, longitude, and additional clean address data.  Note: Applies to off-record Map Objects only. 

Below is an example of a Geopointe Geocode detail page. Note how this record is attached back to the parent record. At the top of the record is the Parent Record look-up field. On that parent record, there is a corresponding Geocode lookup field (it may not be visible on your layout, but it is still there). When a geocode record is created, that lookup field will be populated.

Note: Because the records must be tied to each other to be able to map, any geocode creation will show up as a modification to the parent record. Processes tied to the last modified date should exclude edits to the Geocode field.

Clean Address

If the geocoder could not find the specific address, it will generate as much information as it was able to find and will display this as a clean address in the right column. In the example above, the geocoder was able to add the full postal code and the county.

If the address is not properly entered into the address fields, the geocoder will have trouble parsing the data. Below is an example of an incorrectly-entered address. The geocoder was only able to parse so much; clearly the city is wrong and the street address was read incorrectly.

FAQ

Why are some records not geocoded when the batch job is run the first time, but they are geocoded on subsequent runs of the batch job?
This is due to the the asynchronous nature of the geocoder. When a record is sent out for geocoding, the system checks if the address is already in a cache of geocode records. If it is, the geocoded result is returned instantly. If it is not in the cache, it is added to a processing queue. Sometimes this queue will fill up faster than the geocoder can respond with a result, so the record will not be geocoded right away. However, on the next run, this record will be geocoded instantly because it is in the cache. For this reason, it may take multiple batch job runs to geocode all records in your system.

What are the advantages of On Record geocoding?
The biggest advantage of on-record geocoding is reduced storage requirements.  Due to the way Salesforce calculates database usage, on-record geocoding will not increase your database usage at all.  This can be important to your organization if you are close to your database usage limit.

What are the advantages of Off Record geocoding?
The biggest advantage of off-record geocoding is fewer updates to your records. Even if the address changes and the record needs to be re-geocoded, Geopointe will only modify the Geocode__c record, and not the object record itself. Aside from the first time your record is geocoded, Geopointe will rarely update your record again. This can be important to your organization if you have validation rules, workflows, triggers, or other processes that watch for record updates.
Additionally, off-record geocoding keeps your records cleaner by keeping all geocoding-related fields on a separate record.

How do I switch from Off Record to On Record geocoding (or vice versa)?
To switch, you'll want to edit your map object and follow the instructions on the Map Objects documentation for configuring it as On-Record or Off-Record. 

What address fields do I need to be able to geocode my object?
Your object must have at least one of the following pieces of address or latitude/longitude data to be able to geocode it:
 - Street
 - City
 - State/Province
 - Postal Code
 - Country
 - Latitude AND Longitude
While only one is required, defining more address fields will increase the accuracy of the geocode.

Which geocode fields do I need on my object for On Record and Off Record geocoding?
For on-record geocoding, there are 3 required fields and 7 optional fields:
    Required:
        - Geolocation (type: Geolocation, 7 decimal places is more than enough for almost all uses)
        - Geocode Quality (type: text)
        - Geocode Date Time (type: Datetime)

    Optional: (all are text fields)
        - Clean Street
        - Clean City
        - Clean County
        - Clean State
        - Clean Postal Code
        - Clean Country
        - Clean ISO Country

The optional fields will be populated with the available data received from the geocoder.

For off-record geocoding, there is 1 required field:
        - Geocode Lookup Field (type: lookup to geopointe__Geocode__c object)
    For Account, Contact, Lead, Opportunity, and Case objects, you DO NOT need to create this field unless you are creating a second Map Object for that Salesforce object.

IMPORTANT NOTE: Geopointe supports multiple map objects per Salesforce object. For example, you can have Account - Shipping and Account - Billing map objects.  Each map object will require its own set of geocode fields.