Geopointe

Apex API

Geopointe includes Apex methods customers can use in their own custom Apex code. The following are the methods available for customer use.

geopointe.API Class

geopointe.API Methods

All methods are static methods.

geopointe.API subclasses, enums, and related classes


assignRecords(recordIds, assignmentPlanIds, callbackClassName)
Performs on-demand assignments of the specified records against the specified assignment plans.  If callbackClassName is not null and that class implements the geopointe.APICallback interface, the callback's execute method will be called when all of the Assignment Plans have been fully processed.

Signature
global static String assignRecords(List<Id> recordIds, List<Id> assignmentPlanIds, String callback)

Parameters
recordIds
   Type: List<Id>
   The list of records that will get assigned
assignmentPlanIds
    Type: List<Id>
    The list of Assignment Plans that will be processed
callbackClassName
    Type: String
    The name of a class that you have written that implements the geopointe.APICallback interface.  After all of the plans have been processed, callback will be executed.  Set callback to null if there is no callback.


Usage
A maximum of 1500 record ids can be passed to the function.  The records must be geocoded prior to calling this function.  Records that are not geocoded will not get assigned.  It's important to keep in mind that when you call assignRecords, it will make a lot of asynchronous apex requests and kick off a lot of (sequential) batch jobs.  It is very important that you design and implement your code to avoid hitting SFDC limits.  This is an advanced feature and we highly recommend that only experienced Apex developers use this feature.

Return Value
    Type: String
    The identifier returned by this method call can be used in the callback class to cross-reference requests with callbacks.

checkIn(whereLat, whereLng, note, chatterThis, whatId, whatText)
Performs a check in just like the mobile application would.

Signature
global static String checkIn(Decimal whereLat, Decimal whereLng, String note, Boolean chatterThis, String whatId, String whatText)

Parameters
whereLat
   Type: Decimal 
   User's latitude
whereLng
    Type: Decimal 
    User's longitude
note
    Type: String
    N
ote for the check in (what a user might type in)
chatterThis
   Type: Boolean 
   W
hether or not to Chatter the Check In
whatId
    Type: String 
    T
he Id of the record being checked into. If blank or null, the checkin occurs against the user record
whatText
    Type: String
    The 
text name of the record being checked into (e.g. if whatId is for an account, use the Account Name here)

Return Value
    Type: String
    The Id of the new Checkin record

Example
String checkInID = geopointe.API.checkIn(lat, lng, myNote, true, account.id, account.name);

checkIn(whereLat, whereLng, note, chatterThis, whatId, whatText, chatterImage)
Performs a check in just like the mobile application would

Signature
global static String checkIn(Decimal whereLat, Decimal whereLng, String note, Boolean chatterThis, String whatId, String whatText, Blob chatterImage)

Parameters
whereLat
   Type: Decimal 
   User's latitude
whereLng
    Type: Decimal 
    User's longitude
note
    Type: String
    N
ote for the check in (what a user might type in)
chatterThis
   Type: Boolean 
   W
hether or not to Chatter the Check In
whatId
    Type: String 
    T
he Id of the record being checked into. If blank or null, the checkin occurs against the user record
whatText
    Type: String
    The 
text name of the record being checked into (e.g. if whatId is for an account, use the Account Name here)
chatterImage
    Type: Blob
    The 
image to include in the chatter feed

Return Value
    Type: String
    The id of the new Checkin record

Example
String checkInID = geopointe.API.checkIn(lat, lng, myNote, true, account.id, account.name, myImage);

checkOut(whereLat, whereLng, note, chatterThis, whatId)
Checks out of the last Check In for the corresponding record just like the mobile application would

Signature
global static String checkOut(Decimal whereLat, Decimal whereLng, String note, Boolean chatterThis, String whatId)

Parameters
whereLat
   Type: Decimal 
   User's latitude
whereLng
    Type: Decimal 
    User's longitude
note
    Type: String
    N
ote for the check in (what a user might type in)
chatterThis
   Type: Boolean 
   W
hether or not to Chatter the Check In
whatId
    Type: String 
    T
he Id of the record being checked into. If blank or null, the checkin occurs against the user record

Return Value
    Type: String
    The id of the new Checkin record

Example
String checkOutID = geopointe.API.checkOut(lat, lng, myNote, true, account.id);

checkOut(whereLat, whereLng, note, chatterThis, whatId, chatterImage)
Checks out of the last Check In for the corresponding record just like the mobile application would

Signature
global static String checkOut(Decimal whereLat, Decimal whereLng, String note, Boolean chatterThis, String whatId, Blob chatterImage)

Parameters
whereLat
   Type: Decimal 
   User's latitude
whereLng
    Type: Decimal 
    User's longitude
note
    Type: String
    N
ote for the check in (what a user might type in)
chatterThis
   Type: Boolean 
   W
hether or not to Chatter the Check In
whatId
    Type: String 
    T
he Id of the record being checked into. If blank or null, the checkin occurs against the user record
chatterImage
    Type: Blob
    The 
image to include in the chatter feed

Return Value
    Type: String
    The id of the new Checkin record

Example
String checkOutID = geopointe.API.checkOut(lat, lng, myNote, true, account.id, myImage);

geocodeObject(mapObjectName)
Launches a delta geocode batch job for a specified Map Object.

Signature
global static Map<String, String> geocodeObject(String mapObjectName)

Parameters
mapObjectName
   Type: String
   The name of the Map Object to geocode


Return Value
    Type: Map<String, String>
    The map consists of: { 'processId' => Id of batch job, 'message' => error message if any }

Example
Map<String, String> result = geopointe.API.geocodeObject('account');

geocodeRecord(id)
Synchronously geocodes the record specified

Signature
global static Map<String, String> geocodeRecord(Id recordId)

Parameters
recordId
   Type: Id
   The Id of the record to geocode


Return Value
    Type: Map<String, String>
    The map consists of:
            success => true or false
​            message => error message if any
​            
latitude => latitude of record
​            longitude => longitude of record
​            
geocodeQuality => geocode quality of record

Usage
It is important to note that this performs an HTTP callout. Salesforce will require you to not yet have used DML in your code for the callout to occur.

Example
Map<String, String> result = geopointe.API.geocodeRecord(recordId);

geocodeRecords(List<sObject> records, String mapObjectName)
Synchronously geocode multiple records

Signature
global static Map<String, Object> geocodeRecords(List<sObject> records, String mapObjectName)

Parameters
records
   Type: List<sObject>
   The list of records to geocode.  Limited to 200 records per call.  All records must be of the same type.

mapObjectName
   Type: String
   The api name of the map object to use for geocoding


Return Value
    Type: Map<String, String>
    The map consists of:
            
numSucceeded => Number of records successfully geocoded (Integer) 
​            
errorMessages => Error messages, if any. Empty set if none. (Set<String>)
​            noGeocodeData => Ids of records which could not be geocoded. Empty set if none. (Set<Id>)

Usage
It is important to note that this performs an HTTP callout and a DML operation.  Limited to 200 records per call.

Example
Map<String, Object> results = geopointe.API.geocodeRecords(myAccts, 'account');

geocodeRecords(List<sObject> oldSObjects, List<sObject> newSObjects, Set<String> mapObjectNames, String callbackClassName)
Asynchronously geocode records as needed

Signature
global static void geocodeRecords(List<sObject> oldSObjects, List<sObject> newSObjects, Set<String> mapObjectNames, String callback)

Parameters
oldSObjects
   Type: List<sObject>
   The list of records to geocode.  Limit 200 records per call. (Optional. Pass in null if insert.)  

newSObjects
   Type: List<sObject>
   The list of records to geocode.  Limit 200 records per call.

mapObjectNames
   Type:
Set<String>
   A set of the api name(s) of the map object(s).  If this is null, the addresses for all of the map objects for this sObject type will be geocoded.
callbackClassName
    Type: String
    Currently unused.  Pass in null or any string.

    ​(In the future, you will be able to optionally pass in the name of a class that you have written that implements the geopointe.APICallback interface.  After
    the geocoding is complete, callbackClassName will be executed.  Set callbackClassName to null if there is no callback.)

Usage
This method can only be called from a trigger.  This method will compare the old and new lists and only geocode objects if their relevant address(es) have changed.  If oldSObjects is null (e.g. on insert), it will geocode all of the records in newSObjects.  

It is important to note that this performs one future call per map object.  Y
ou must design and implement your code to avoid hitting SFDC limits.​  The geocoding is performed when the future call executes, and Salesforce controls when that occurs. 

Examples
// only geocode records whose addresses have changed.  geocode using all map objects for this sobject
geopointe.API.geocodeRecords(Trigger.old, Trigger.new, null, null);

// geocode all of the records, and only geocode the addresses for the specified map objects 
geopointe.API.geocodeRecords(null, newAccts, new Set<String>{'account', 'account_custom'}, null);

getAPIDailyCreditsAvailable()
Returns number of remaining daily API credits available.

Signature
global static Decimal getAPIDailyCreditsAvailable()

Return Value
    Type: Decimal

Example
Decimal remainingAPICredits = geopointe.API.getAPIDailyCreditsAvailable();

getAPIPaidCreditsAvailable()
Returns number of remaining paid API credits available.

Signature
global static Decimal getAPIPaidCreditsAvailable()

Return Value
    Type: Decimal

Example
Decimal remainingAPICredits = geopointe.API.getAPIPaidCreditsAvailable();

getDataSetDetail(dataSetIdentifier)
Returns a geopointe.API.DataSetDetail object

Signature
global static DataSetDetail getDataSetDetail(String dataSetIdentifier)

Parameters
dataSetIdentifier
   Type: String
   The data set identifier. 
This can be obtained from the getDataSets call or interactively on the Geopointe Map page by editing the data set and clicking the "Other" tab.  A typical identifier looks like: ​13226166487910.11193988490038331

Return Value
    Type: geopointe.API.DataSetDetail 

Example
geopointe.API.DataSetDetail mydataset = geopointe.API.getDataSetDetail('13226166487910.11193988490038331');

getDataSets(publicDataSets, userIds)
Returns a list of geopointe.API.DataSet objects

Signature
global static List<DataSet> getDataSets(Boolean publicDataSets, Set<Id> userIds)

Parameters
publicDataSets
   Type: Boolean 
   Flag to indicate if public data sets should be returned
userIds
    Type: Set<Id>
    If not null or empty, will return private data sets owned by those users


Return Value
    Type: List<geopointe.API.DataSet>

Examples
//Returns all public Data Sets
dataSets = geopointe.API.getDataSets(true,null);

//Returns all public Data Sets and the current user’s private Data Sets
dataSets = geopointe.API.getDataSets(true,new Set{UserInfo.getUserId()});

//Returns no public Data Sets and only the current user’s private Data Sets
dataSets = geopointe.API.getDataSets(false,new Set{UserInfo.getUserId()});

getDistance(recordId1, recordId2, units)
Returns the straight-line distance (miles or kilometers) between two records

Signature
global static Double getDistance(Id recordId1, Id recordId2, geopointe.API.Units units)

Parameters
recordId1
   Type: Id
   Id of first record

recordId2
    Type: Id
    Id of second record
units
    Type: geopointe.API.units
    An enum: 
geopointe.API.units.MILES or geopointe.API.units.KILOMETERS

Return Value
    Type: Double

Example
Double dist = geopointe.API.getDistance(account1.Id, account2.Id, geopointe.API.units.MILES);

getDistance(lat, lng, recordId, units)
Returns the straight-line distance (miles or kilometers) between a latitude/longitude point and a record

Signature
global static Double getDistance(Decimal lat, Decimal lng, Id recordId, geopointe.API.units units)
global static Double getDistance(Double lat, Double lng, Id recordId, geopointe.API.units units)

Parameters
lat
   Type: Decimal or Double
   Latitude

lng
   Type: Decimal or Double
   Longitude

recordId
    Type: Id
    Id of record
units
    Type: geopointe.API.units
    An enum: 
geopointe.API.units.MILES or geopointe.API.units.KILOMETERS

Return Value
    Type: Double

Example
Double dist = geopointe.API.getDistance(lat, lng, account.Id, geopointe.API.units.MILES);

getDistance(lat1, lng1, lat2, lng2, units)
Returns the straight-line distance (miles or kilometers) between 2 latitude/longitude points

Signature
global static Double getDistance(Decimal lat1, Decimal lng1, Decimal lat2,  Decimal lng2, geopointe.API.units units)
global static Double getDistance(Double lat1, Double lng1, Double lat2,  Double lng2, geopointe.API.units units)


Parameters
lat1
   Type: Decimal or Double
   Latitude of first point

lng1
   Type: Decimal or Double
   Longitude of first point

lat2
   Type: Decimal or Double
   Latitude of second point

lng3
   Type: Decimal or Double
   Longitude of second point

units
    Type: geopointe.API.units
    An enum: geopointe.API.units.MILES or geopointe.API.units.KILOMETERS


Return Value
    Type: Double

Example
Double dist = geopointe.API.getDistance(lat1, lng1, lat2, lng2, geopointe.API.units.KILOMETERS);

getDMLSource()
Returns a geopointe.API.DMLSource enum value to indicate the type process running

Signature
global static DMLSource getDMLSource()

Return Value
    Type: geopointe.API.DMLSource
    { GEOCODE_JOB_SCHEDULE_DELTA, GEOCODE_JOB_MANUAL_ALL, GEOCODE_JOB_MANUAL_DELTA, MAP_OBJECT_CHANGE }

Example
if (geopointe.API.getDMLSource() == geopointe.API.DMLSource.GEOCODE_JOB_SCHEDULE_DELTA) { ... }

goToRecordMap(id, setRedirect)
Returns a Page Reference that will sends a user to the map page for a specific record

Signature
global static PageReference goToRecordMap(Id recordId, Boolean setRedirect)

Parameters
recordId
   Type: Id
   The record to map
setRedirect
    Type: Boolean
    setRedirect flag


Return Value
    Type: PageReference

Example
PageReference pr = geopointe.API.goToRecordMap(account.Id, true);

initGeopointeDataForTests()
A method that can only be used in tests to initialize the Geopointe app with test data

Signature
global static void initGeopointeDataForTests()

Usage
    When you are writing tests to cover your own custom processes and code, you can initialize the Geopointe app with this method.  This can only be used in test methods.

Example
geopointe.API.initGeopointeDataForTests();

launchAnalyticsDataSetBatchJob(dataSetIdentifier, orgWide)
Launches an Analytics Batch Job

Signature
global static String launchAnalyticsDataSetBatchJob(String dataSetIdentifier, Boolean orgWide)

Parameters
dataSetIdentifier
   Type: String
   The data set identifier. 
This can be obtained from the getDataSets call or interactively on the Geopointe Map page by editing the data set and clicking the "Other" tab.  A typical identifier looks like: ​13226166487910.11193988490038331
orgWide
    Type: Boolean
    Flag to indicate if it should be an org-wide data set


Return Value
    Type: String
    The Id of the batch job

Example
String processId = geopointe.API.launchAnalyticsDataSetBatchJob('13226166487910.11193988490038331', false);

radialSearchDataSet(recordId, dataSetIdentifier, range, units)
Performs a radial search using a defined Data Set. Returns a geopointe.API.radialSearchResult object

Signature
global static RadialSearchResult radialSearchDataSet(Id recordId, String dataSetIdentifier, Decimal range, geopointe.API.units units)

Parameters
recordId
   Type: Id
   The Id of the record to search around

dataSetIdentifier
   Type: String
   The data set identifier. 
This can be obtained from the getDataSets call or interactively on the Geopointe Map page by editing the data set and clicking the "Other" tab.  A typical identifier looks like: ​13226166487910.11193988490038331
range
    Type: Decimal 
    The search radius
units
    Type: geopointe.API.units
    An enum: geopointe.API.units.MILES or geopointe.API.units.KILOMETERS


Return Value
    Type: geopointe.API.RadialSearchResult

Example
geopointe.API.RadialSearchResult result = geopointe.API.radialSearchDataSet(account.Id, ‘12825203386670.18644033148613703’, 25, geopointe.API.units.MILES);

radialSearchDataSet(latitude, longitude, dataSetIdentifier, range, units)
Performs a radial search around the provided latitude and longitude using a defined Data Set. Returns a geopointe.API.radialSearchResult object

Signature
global static RadialSearchResult radialSearchDataSet(Id recordId, String dataSetIdentifier, Decimal range, geopointe.API.units units)

Parameters
latitude
   Type: Decimal
   The latitude for the center point of the search

longitude
   Type: Decimal
   The longitude for the center point of the search
dataSetIdentifier
   Type: String
   The data set identifier. 
This can be obtained from the getDataSets call or interactively on the Geopointe Map page by editing the data set and clicking the "Other" tab.  A typical identifier looks like: ​13226166487910.11193988490038331
range
    Type: Decimal 
    The search radius
units
    Type: geopointe.API.units
    An enum: geopointe.API.units.MILES or geopointe.API.units.KILOMETERS


Return Value
    Type: geopointe.API.RadialSearchResult

Example
geopointe.API.RadialSearchResult result = geopointe.API.radialSearchDataSet(account.Id, ‘12825203386670.18644033148613703’, 25, geopointe.API.units.MILES);

radialSearchMapObject(id, mapObjectName, whereClause, range, units)
Performs a radial search against a Map Object. Returns a geopointe.API.radialSearchResult object

Signature
global static RadialSearchResult radialSearchMapObject(Id recordId, String mapObjectName, String whereClause, Decimal range,  geopointe.API.units units)

Parameters
recordId
   Type: Id
   The Id of the record to search around

mapObjectName
   Type: String
   The API Name of the Map Object to search for

range
    Type: Decimal 
    The search radius
whereClause
    Type: String 

    A SOQL where clause (without the WHERE keyword) if a custom filter should be applied to the search. If no filter should be applied, null or '' can be passed in
units
    Type: geopointe.API.units
    An enum: geopointe.API.units.MILES or geopointe.API.units.KILOMETERS


Return Value
    Type: geopointe.API.RadialSearchResult

Example
geopointe.API.radialSearchResult result = geopointe.API.radialSearchMapObject(lead.Id, 'account', 'type=\'Customer\'', 25, geopointe.API.units.MILES);

radialSearchMapObject(latitude, longitude, mapObjectName, whereClause, range, units)
Performs a radial search against a Map Object around the provided latitude and longitude. Returns a geopointe.API.radialSearchResult object

Signature
global static RadialSearchResult radialSearchMapObject(Decimal latitude, Decimal longitude, String mapObjectName, String whereClause, Decimal range,  geopointe.API.units units)

Parameters
latitude
   Type: Decimal
   The latitude for the center point of the search

longitude
   Type: Decimal
   The longitude for the center point of the search
mapObjectName
   Type: String
   The API Name of the Map Object to search for

range
    Type: Decimal 
    The search radius
whereClause
    Type: String 

    A SOQL where clause (without the WHERE keyword) if a custom filter should be applied to the search. If no filter should be applied, null or '' can be passed in
units
    Type: geopointe.API.units
    An enum: geopointe.API.units.MILES or geopointe.API.units.KILOMETERS


Return Value
    Type: geopointe.API.RadialSearchResult

Example
geopointe.API.radialSearchResult result = geopointe.API.radialSearchMapObject(lead.Id, 'account', 'type=\'Customer\'', 25, geopointe.API.units.MILES);
 

geopointe.API.RadialSearchResult Properties

Property Data Type Description
error Boolean True or false whether an error occurred.
errorMessage String If error is true, this field will contain the message as to why.
mapObjectName String Confirms the map object the data was retrieved from.
dataSetName String Returns the name of the Data Set. This will be the name the user is used to seeing in the UI.
recordsInDistanceOrder List A list of record IDs in the order of nearest to farthest.
recordsByDistance Map A map of record Id to its distance.
recordCount Integer How many records were returned. Should equal the size of the list and map above.
query String The SOQL that was performed – currently not being populated.


geopointe.API.DataSet Properties

Property Data Type Description
uniqueId String The unique Identifier of a Data Set. Example) 13226166487910.11193988490038331
name String The Name of a Data Set.
accessLevel String Will return ‘public’ if the data set is visible to all users and ‘private’ if it is a user created Data Set.
availableInMaps Boolean Indicates whether the Data Set is available on the Map tab and on Mobile devices.
availableInVisualize Boolean Indicates whether the Data Set is available on the Visualize tab.
color String The color of markers on the map in hexadecimal format without the # symbol. Example) ‘236FBD’
colorMarkersByFieldName String Returns the field name of the default Color Markers By selection for the Data Set.
createdDate DateTime Date and time the Data Set was created.
lastModifiedDate DateTime Date and time the Data Set was last modified.
mapObjectName String The salesforce.com object name this Data Set is used for. Example) ‘Account’ or ‘Widget__c’. This may be returned as all lowercase.
myRecords Boolean Indicates if the Data Set should only return records owned by the current user.
oneColumnAddress Boolean Indicates if the address is outputted on one line on the Map page tables.
orderByDirection String Retruns the order by direction for the orderByFieldName property. Returned value may be ‘asc’ or ‘desc’.
orderByFieldName String Returns the name of the object field in which search results should be ordered.
ownerId Id Returns the OwnerId. For private Data Sets this will be a User Id. For public Data Sets this will be the salesforce.com Organization Id.
 

geopointe.API.DataSetDetail Properties

Property Data Type Description
ds geopointe.API.Dataset The Data Set
dsFields List<geopointe.API.DataSetField> List of fields
dsFilters List<geopointe.API.DataSetFilter> List of filters
 

geopointe.API.DataSetField Properties

Property Data Type Description
uniqueId String  
dsId String The unique Identifier of a Data Set. Example) 13226166487910.11193988490038331
field String  
sObjectName String  
order Decimal  
createdDate DateTime  
lastModifiedDate DateTime  

geopointe.API.DataSetFilter Properties

Property Data Type Description
uniqueId String  
dsId String The unique Identifier of a Data Set. Example) 13226166487910.11193988490038331
field String  
fieldType String  
operator String  
filterValue String  
childSObjectName String  
childRelationshipName String  
childField String  
childInNotIn String  
createdDate DateTime  
lastModifiedDate DateTime  
order Double  
sObjectName String  
 

geopointe.APICallback Interface

The geopointe.APICallback Interface has only one method that needs to be implemented:
void execute(String methodName, String requestId, Map<String, Object> args);
​When the On-Demand Assignments complete, it will invoke your callback class and pass it:
methodName = 'assignRecords'
requestId = the unique identifier that was returned when you called assignRecords
args =
{
   startTime: DateTime
   endTime: DateTime
   recordIds: List<Id>   
   errorMessages: List<String>
}