Geopointe

Distance Service API

DistanceService is a subclass of the Geopointe Apex API and contains methods for calculating the driving distance between two locations. If you are looking for a straight-line ("as the crow flies") distance, you can use our getDistance methods instead, as those methods have no usage limitations.

geopointe.API.DistanceService class

Usage

Create a new instance of the DistanceService class.  Add up to 200 origin destination pairs.  Then call any get functions.  Attempting to add more origin destination pairs after calling a get function will result in an error.

geopointe.API.DistanceService Constructors

  • DistanceService()
    Creates a new instance of the geopointe.API.DistanceService class

geopointe.API.DistanceService Methods

  • add(origin, destination)
    Adds an origin destination pair to the distance service (limited to 200 per DistanceService instance)
  • add(origin, lat2, lng2)
    Adds an origin destination pair to the distance service (limited to 200 per DistanceService instance)
  • add(lat1, lng1, destination)
    Adds an origin destination pair to the distance service (limited to 200 per DistanceService instance)
  • add(lat1, lng1, lat2, lng2)
    Adds an origin destination pair to the distance service (limited to 200 per DistanceService instance)
  • getDistanceAtIndex(index)
    Returns the distance between the origin and destination at the given index. Each pair counts towards the purchased distance API limit
  • getListOfDistances()
    Returns the list of distances between the origin and destination pairs. Each pair counts towards the purchased distance API limit
  • getListOfTravelTimes()
    Returns the list of travel times in seconds between the origin and destination pairs. Each pair counts towards the purchased distance API limit
  • getTravelTimeAtIndex(index)
    Returns the travel time in seconds between the origin and destination at the given index. Each pair counts towards the purchased distance API limit
  • setMode(mode)
    Sets the mode of travel for distance calculations to driving or walking (driving by default)
  • setUnits(units)
    Sets the units for distance calculations to miles or kilometers (miles by default)

‚Äč

add(origin, destination)
Adds an origin destination pair to the distance service (limited to 200 per DistanceService instance)

Signature
global void add(String origin, String destination)

Parameters
origin
   Type: String
   
String containing start location
destination
    Type: String
    
String containing end location

Return Value
    Type: Void

Example
geopointe.API.DistanceService ds = new geopointe.API.DistanceService();
ds.add('Orange,CA', 'Petaluma,CA');
add(origin, lat2, lng2)
Adds an origin destination pair to the distance service (limited to 200 per DistanceService instance)

Signature
global void add(String origin, Decimal lat2, Decimal lng2)
global void add(String origin, Double lat2, Double lng2)

Parameters
origin
   Type: String
   
String containing start location
lat2
    Type: Double or Decimal
    Latitude of the end location

lng2
    Type: Double or Decimal
    Longitude of the end location


Return Value
    Type: Void

Example
geopointe.API.DistanceService ds = new geopointe.API.DistanceService();
ds.add('Orange,CA', 38.2314, -122.6167);
add(lat1, lng1, destination)
Adds an origin destination pair to the distance service (limited to 200 per DistanceService instance)

Signature
global void add(Decimal lat1, Decimal lng1, String destination)
global void add(Double lat1, Double lng1, String destination)

Parameters
lat1
    Type: Double or Decimal
    Latitude of the start location

lng1
    Type: Double or Decimal
    Longitude of the start location

destination
    Type: String
    String containing end location


Return Value
    Type: Void

Example
geopointe.API.DistanceService ds = new geopointe.API.DistanceService();
ds.add(33.7870, -117.8557, 'Petaluma,CA');
add(lat1, lng1, lat2, lng2)
Adds an origin destination pair to the distance service (limited to 200 per DistanceService instance)

Signature
global void add(Decimal lat1, Decimal lng1, Decimal lat2, Decimal lng2)
global void add(Double lat1, Double lng1, Double lat2, Double lng2)

Parameters
lat1
    Type: Double or Decimal
    Latitude of the start location

lng1
    Type: Double or Decimal
    Longitude of the start location

lat2
    Type: Double or Decimal
    Latitude of the end location

lng2
    Type: Double or Decimal
    Longitude of the end location


Return Value
    Type: Void

Example
geopointe.API.DistanceService ds = new geopointe.API.DistanceService();
ds.add(33.7870, -117.8557, 38.2314, -122.6167);
getDistanceAtIndex(index)
Returns the distance between the origin and destination at the given index. Each pair counts towards the purchased distance API limit

Signature
global Double getDistanceAtIndex(Integer index)

Parameters
index
   Type: Integer
   An Integer 
0 to 19 based on the order origin destination pairs were added

Return Value
    Type: Double
    Distance in miles or kilometers.  Default is miles.  Can use setUnits(units) to change the units.


Example
geopointe.API.DistanceService ds = new geopointe.API.DistanceService(); 
ds.add(33.7870, -117.8557, 38.2314, -122.6167); 
ds.add('Orange,CA', 'Petaluma,CA'); 
Double sum = ds.getDistanceAtIndex(0) + ds.getDistanceAtIndex(1);
getListOfDistances()
Returns the list of distances between the origin and destination pairs. Each pair counts towards the purchased distance API limit

Signature
global List<Double> getListOfDistances()

Return Value
    Type: List<Double>
    Distances are miles or kilometers.  Default is miles.  Can use setUnits(units) to change the units.


Example
geopointe.API.DistanceService ds = new geopointe.API.DistanceService(); 
ds.add(33.7870, -117.8557, 38.2314, -122.6167); 
ds.add('Orange,CA', 'Petaluma,CA'); 
List<double> distances = ds.getListOfDistances();
getListOfTravelTimes()
Returns the list of travel times in seconds between the origin and destination pairs. Each pair counts towards the purchased distance API limit

Signature
global List<Double> getListOfTravelTimes()

Return Value
    Type: List<Double>
    Times are in seconds


Example
geopointe.API.DistanceService ds = new geopointe.API.DistanceService(); 
ds.add(33.7870, -117.8557, 38.2314, -122.6167); 
ds.add('Orange,CA', 'Petaluma,CA'); 
List<double> travelTimes = ds.getListOfTravelTimes();
getTravelTimeAtIndex(index)
Returns the travel time in seconds between the origin and destination at the given index. Each pair counts towards the purchased distance API limit

Signature
global Double getTravelTimeAtIndex(Integer index)

Parameters
index
   Type: Integer
   An Integer 
0 to 19 based on the order origin destination pairs were added

Return Value
    Type: Double
    Time is in seconds


Example
geopointe.API.DistanceService ds = new geopointe.API.DistanceService(); 
ds.add(33.7870, -117.8557, 38.2314, -122.6167); 
ds.add('Orange,CA', 'Petaluma,CA'); 
Double sum =  ds.getTravelTimeAtIndex(0) + ds.getTravelTimeAtIndex(1);
setMode(mode)
Sets the mode of travel for distance calculations to driving or walking (driving by default)

Signature
global void setMode(geopointe.API.mode mode)

Parameters
mode
   Type: geopointe.API.mode
   Options are geopointe.
API.mode.DRIVING, geopointe.API.mode.WALKING

Return Value
    Type: void

Example
geopointe.API.DistanceService ds = new geopointe.API.DistanceService(); 
ds.setMode(geopointe.API.mode.WALKING);
setUnits(units)
Sets the units for distance calculations to miles or kilometers (miles by default)

Signature
global void setUnits(geopointe.API.units units)

Parameters
units
   Type: geopointe.API.units
   Options are geopointe.API.units.MILES, geopointe.API.units.KILOMETERS


Return Value
    Type: void

Example
geopointe.API.DistanceService ds = new geopointe.API.DistanceService(); 
ds.setUnits(geopointe.API.KILOMETERS);

Example Using Accounts and Off-Record Geocoding

geopointe.API.DistanceService ds = new geopointe.API.DistanceService();
List<Account> accList = [SELECT id, distance__c, geopointe__Geocode__r.geopointe__Latitude__c, geopointe__Geocode__r.geopointe__Longitude__c FROM Account LIMIT 1];
List<Account> origins = new List<Account>();
List<Account> destinations = new List<Account>();

// Split up data into origins and destinations
for(Integer i = 0; i < accList.size(); i++){
   if(Math.mod(i, 2) == 0){
       origins.add(accList.get(i));
   }else{
       destinations.add(accList.get(i));
   }
}

// Add the latitude and longitudes for the origin destination pairs
for(Integer i = 0; i < origins.size(); i++){
    ds.add((Double)origins.get(i).geopointe__Geocode__r.geopointe__Latitude__c,
        (Double)origins.get(i).geopointe__Geocode__r.geopointe__Longitude__c,
        (Double)destinations.get(i).geopointe__Geocode__r.geopointe__Latitude__c,
        (Double)destinations.get(i).geopointe__Geocode__r.geopointe__Longitude__c);
}

// Get the distance results and update desired fields
for(Integer i = 0; i < origins.size(); i++){
    Double distance = ds.getDistanceAtIndex(i);
    origins.get(i).distance__c = distance;
    destinations.get(i).distance__c = distance;
}
update accList;

Licensing

Every Geopointe subscription is granted a limited number of free API Service calls. The DistanceService falls within the API Service calls limit. The current balance of remaining calls can be found on the Geopointe Setup page. Additional service calls can be provided for a fee. Learn more at http://geopointe.com/pricing.