Distance Time Matrix Matrix RequestMatrix Request

Overview

The Matrix Request defines a model for which a matrix should be calculated. The matrix request is serialised as any other model would into a problem envelope and submitted to the matrix route.

Applicable models

• Matrix matrix-vyv95n7wchpl

Endpoint

• POST: https://api.icepack.ai/matrix/

eDurationUnit

Defines the time units in which the response should be provided.

Schema definition

enum eDurationUnit{
  SECONDS = 0;
  MINUTES = 1;
  HOURS = 2;
  DAYS = 3;
}

eDistanceUnit

Defines the distance units in which the response should be provided.

Schema definition

enum eDistanceUnit {
  KILOMETRES = 0;
  MILES = 1;
}

Matrix Request

Schema definition

message MatrixRequest{
  repeated Location locations = 1;
  repeated string sources = 2;
  repeated string destinations = 3;
  required eDistanceUnit distanceUnit = 4 [default = KILOMETRES];
  required eDurationUnit durationUnit = 5 [default = MINUTES];
}

Fields

locations

A list of unique locations which are referenced by the sources and destinations fields in the matrix request.

sources

A list of location id’s which define the “from” or source locations of the required matrix.

destinations

A optional list of location id’s which define the “to” or destination locations of the required matrix. If omitted, all n^2 distance/durations are computed between all sources, which is equivalent to providing the list of sources as the destinations.

distanceUnit

The unit in which the distance should be returned in the matrix elements.

durationUnit

The unit in which the times should be returned in the matrix elements.

Examples

This example illustrates a request for a 3x3 matrix. The corresponding matrix response will consist of 6 elements as the diagonal elements are all zero and are omitted from the response. In general, for square matrices of size n, a total of (n).(n-1) elements are returned by the API.

locations {
  id: "The Oval Bar Dublin"
  geocode {
    longitude: -6.26029587
    latitude: 53.3484612
  }
}
locations {
  id: "The Confession Box"
  geocode {
    longitude: -6.25840282
    latitude: 53.3503418
  }
}
locations {
  id: "Kehoes Pub"
  geocode {
    longitude: -6.25942898
    latitude: 53.3411598
  }
}
sources: "The Oval Bar Dublin"
sources: "The Confession Box"
sources: "Kehoes Pub"
distanceUnit: KILOMETRES
durationUnit: HOURS

This next example illustrates generating a 2x4 matrix. Two sources and four destinations are provided. Note that the sources and destinations are disjoint in that they do not overlap. This does not have to be the case as we could have included the sources in the destinations list which would result in a 2x6 matrix. It does highlight, however, that all the locations are required (the union of sources and destinations) in the locations list. This example also illustrates a variation on the units (Miles and Minutes between locations).

locations {
  id: "The Long Hall"
  geocode {
    longitude: -6.26529789
    latitude: 53.3418503
  }
}
locations {
  id: "Nearys"
  geocode {
    longitude: -6.26119
    latitude: 53.3407516
  }
}
locations {
  id: "McDaids"
  geocode {
    longitude: -6.26100302
    latitude: 53.3412209
  }
}
locations {
  id: "Johnnie Fox's Pub"
  geocode {
    longitude: -6.21919918
    latitude: 53.2217102
  }
}
locations {
  id: "Davy Byrne's pub"
  geocode {
    longitude: -6.25934
    latitude: 53.3418503
  }
}
locations {
  id: "The Dropping Well"
  geocode {
    longitude: -6.2550621
    latitude: 53.307991
  }
}
locations {
  id: "John Kavanagh The Gravediggers"
  geocode {
    longitude: -6.27199
    latitude: 53.3696404
  }
}
sources: "The Long Hall"
sources: "Nearys"
destinations: "McDaids"
destinations: "Johnnie Fox's Pub"
destinations: "Davy Byrne's pub"
destinations: "The Dropping Well"
distanceUnit: MILES
durationUnit: MINUTES