The Geocoder

The Geocoder is a process running in the background of Geopointe, continually monitoring your data for additions and changes, preparing it for mapping. 

What is geocoding? Geocoding is the process of taking and address and converting it to latitude and longitude coordinates so it can be placed on a map.

Ways to Run the Geocoder

Scheduled Job

Recommended. If you have not done so, in order to receive geocoding results, you need to have it scheduled to run. You do this in the Geopointe Setup tab. Navigate to the Batch Jobs section. Click Schedule Job. 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, how often it will run, and the next scheduled runtime. Once it has run the first time you have Geocode data available to you under the Geocodes tab.


From the Geopointe Setup tab, under the Map Objects tab, there is a field on the far right for Geocode Batches. This is your method for manually running the Geocoder rather than the hourly schedule. If you choose All, the Geocoder will completely re-evaluate that entire object (needed rarely, typically for troubleshooting purposes). If you just want to run an update, choose Delta.

Geocode Quality

The geocoder also returns a value to tell you how accurate it was able to be. The two samples above demonstrate two opposing levels of accuracy. You’ll want as many records to read ADDRESS as possible. Remember that it is the cleansed address that will map in the system; if the cleansed address doesn’t have enough data to map properly, the location will be incorrect.

Geopointe uses three colors to distinguish between the qualities. Here are the quality levels with their corresponding colors:

  • 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.

Longitude and Latitude

The Geocoder also returns the longitude and latitude for each record. There are currently 3 sets of latitude and longitude. 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 using customer provided longitude and latitude values, the box next to Uses Customer Geocodes is checked.

Processing Speed

The geocoder runs very quickly, able to process 1000+ 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 from the Batch Jobs tab in Geopointe Setup.

The Geocodes Tab

This applies for Off Record Geocoding only! From the Geocodes tab, you can search and view the geocode for every record that has been scheduled and run. The Geocoder returns information such as the latitude, longitude, and other address information. This information comes as part of the address cleansing, when the geocoder parses the address to find the most accurate address location possible.

A full geocode entry looks like this:

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 become 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.

Cleansed Address

You’ll see on the left the original address that someone within the company added to Salesforce. On the right you’ll see the “cleaned” version of the address. The geocoder was able to plug in the entire zip code and identify the county.

If the geocoder could not find the specific address, the cleansed address will generate as much information as it was able to confirm. 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.


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 we check to see if that address is already in a cache of geocode records. If it is we return the geocoded result instantly. If the address being requested for geocode is not in the cache it is added to a processing queue. Sometimes this queue will fill up faster than the Geocoder can responded with a result. In this case the record processed by the Geocoder will not be geocode. On the next run this record will be requested for geocoding again and on this second run the address will be in the cache and should be geocoded instantly. In summation, 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.  Other than the first time your record is geocoded, Geopointe will rarely update your record again.  Even if the address changes and the record needs to be re-geocoded, Geopointe will not update your record, since we will only be modifying the Geocode__c record.  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 whichever one you want to switch to.

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.

What 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:
        - 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 type: text)
        - Clean Street
        - Clean City
        - Clean County
        - Clean State
        - Clean Postal Code
        - Clean Country
        - Clean ISO Country

The optional fields will be populated with available data we receive back from the geocoding service.

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: We support having multiple map objects per Salesforce object.  This means, for example, that you can have "Account - Shipping" and "Account - Billing" map objects.  Each map object will require its own set of geocode fields.