culparepellendus 1.0.0

package/packages/arcgis-rest-routing/src/closestFacility.ts

@@ -0,0 +1,225 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  cleanUrl,
+  appendCustomParams,
+} from "@esri/arcgis-rest-request";
+
+import {
+  ILocation,
+  IPoint,
+  IFeature,
+  IFeatureSet,
+} from "@esri/arcgis-rest-types";
+
+import {
+  ARCGIS_ONLINE_CLOSEST_FACILITY_URL,
+  IEndpointOptions,
+  normalizeLocationsList,
+  isFeatureSet,
+} from "./helpers";
+
+import { arcgisToGeoJSON } from "@terraformer/arcgis";
+
+export interface IClosestFacilityOptions extends IEndpointOptions {
+  /**
+   * Specify one or more locations from which the service searches for the nearby locations. These locations are referred to as incidents.
+   */
+  incidents: Array<IPoint | ILocation | [number, number]> | IFeatureSet;
+
+  /**
+   * Specify one or more locations that are searched for when finding the closest location.
+   */
+  facilities: Array<IPoint | ILocation | [number, number]> | IFeatureSet;
+  /**
+   *  Specify if the service should return routes.
+   */
+  returnCFRoutes: boolean;
+  travelDirection?: "incidentsToFacilities" | "facilitiesToIncidents";
+  barriers?: Array<IPoint | ILocation | [number, number]> | IFeatureSet;
+  polylineBarriers?: IFeatureSet;
+  polygonBarriers?: IFeatureSet;
+  returnDirections?: boolean;
+  directionsOutputType?:
+    | "esriDOTComplete"
+    | "esriDOTCompleteNoEvents"
+    | "esriDOTInstructionsOnly"
+    | "esriDOTStandard"
+    | "esriDOTSummaryOnly"
+    | "esriDOTFeatureSets";
+  directionsLengthUnits?:
+    | "esriNAUCentimeters"
+    | "esriNAUDecimalDegrees"
+    | "esriNAUDecimeters"
+    | "esriNAUFeet"
+    | "esriNAUInches"
+    | "esriNAUKilometers"
+    | "esriNAUMeters"
+    | "esriNAUMiles"
+    | "esriNAUMillimeters"
+    | "esriNAUNauticalMiles"
+    | "esriNAUPoints"
+    | "esriNAUYards";
+  outputLines?: boolean;
+  returnFacilities?: boolean;
+  returnIncidents?: boolean;
+  returnBarriers?: boolean;
+  returnPolylineBarriers?: boolean;
+  returnPolygonBarriers?: boolean;
+  preserveObjectID?: boolean;
+}
+
+interface IFeatureSetWithGeoJson extends IFeatureSet {
+  geoJson?: any;
+}
+
+export interface IClosestFacilityResponse {
+  messages: string[];
+  routes?: IFeatureSetWithGeoJson;
+  directions?: Array<{
+    routeId: number;
+    routeName: string;
+    summary: object;
+    features: IFeature[];
+  }>;
+  incidents?: IFeatureSet;
+  facilities?: IFeatureSet;
+  barriers?: IFeatureSet;
+  polygonBarriers?: IFeatureSet;
+  polylineBarriers?: IFeatureSet;
+}
+
+function getTravelDirection(
+  key: "incidentsToFacilities" | "facilitiesToIncidents"
+): "esriNATravelDirectionFromFacility" | "esriNATravelDirectionToFacility" {
+  if (key === "incidentsToFacilities") {
+    return "esriNATravelDirectionFromFacility";
+  } else {
+    return "esriNATravelDirectionToFacility";
+  }
+}
+
+/**
+ * ```js
+ * import { closestFacility } from '@esri/arcgis-rest-routing';
+ * //
+ * closestFacility({
+ *   incidents: [
+ *     [-90.404302, 38.600621],
+ *     [-90.364293, 38.620427],
+ *    ],
+ *   facilities: [
+ *     [-90.444716, 38.635501],
+ *     [-90.311919, 38.633523],
+ *     [-90.451147, 38.581107]
+ *    ],
+ *    authentication
+ * })
+ *   .then(response) // => {routes: {features: [{attributes: { ... }, geometry:{ ... }}]}
+ * ```
+ * Used to find a route to the nearest of several possible destinations. See the [REST Documentation](https://developers.arcgis.com/rest/network/api-reference/closest-facility-synchronous-service.htm) for more information.
+ *
+ * @param requestOptions Options to pass through to the routing service.
+ * @returns A Promise that will resolve with routes and directions for the request.
+ * @restlink https://developers.arcgis.com/rest/network/api-reference/closest-facility-synchronous-service.htm
+ */
+export function closestFacility(
+  requestOptions: IClosestFacilityOptions
+): Promise<IClosestFacilityResponse> {
+  const endpoint =
+    requestOptions.endpoint || ARCGIS_ONLINE_CLOSEST_FACILITY_URL;
+
+  requestOptions.params = {
+    returnFacilities: true,
+    returnDirections: true,
+    returnIncidents: true,
+    returnBarriers: true,
+    returnPolylineBarriers: true,
+    returnPolygonBarriers: true,
+    preserveObjectID: true,
+    ...requestOptions.params,
+  };
+
+  const options = appendCustomParams<IClosestFacilityOptions>(requestOptions, [
+    "returnCFRoutes",
+    // "travelDirection",
+    "barriers",
+    "polylineBarriers",
+    "polygonBarriers",
+    "returnDirections",
+    "directionsOutputType",
+    "directionsLengthUnits",
+    "outputLines",
+    "returnFacilities",
+    "returnIncidents",
+    "returnBarriers",
+    "returnPolylineBarriers",
+    "returnPolygonBarriers",
+    "preserveObjectID",
+  ]);
+
+  // Set travelDirection
+  if (requestOptions.travelDirection) {
+    options.params.travelDirection = getTravelDirection(
+      requestOptions.travelDirection
+    );
+  }
+
+  // the SAAS service does not support anonymous requests
+  if (
+    !requestOptions.authentication &&
+    endpoint === ARCGIS_ONLINE_CLOSEST_FACILITY_URL
+  ) {
+    return Promise.reject(
+      "Finding the closest facility using the ArcGIS service requires authentication"
+    );
+  }
+
+  if (isFeatureSet(requestOptions.incidents)) {
+    options.params.incidents = requestOptions.incidents;
+  } else {
+    options.params.incidents = normalizeLocationsList(
+      requestOptions.incidents
+    ).join(";");
+  }
+
+  if (isFeatureSet(requestOptions.facilities)) {
+    options.params.facilities = requestOptions.facilities;
+  } else {
+    options.params.facilities = normalizeLocationsList(
+      requestOptions.facilities
+    ).join(";");
+  }
+
+  // optional input param that may need point geometry normalizing
+  if (requestOptions.barriers) {
+    if (isFeatureSet(requestOptions.barriers)) {
+      options.params.barriers = requestOptions.barriers;
+    } else {
+      // optional point geometry barriers must be normalized, too
+      // but not if provided as IFeatureSet type
+      // note that optional polylineBarriers and polygonBarriers do not need to be normalized
+      options.params.barriers = normalizeLocationsList(
+        requestOptions.barriers
+      ).join(";");
+    }
+  }
+
+  return request(`${cleanUrl(endpoint)}/solveClosestFacility`, options).then(
+    cleanResponse
+  );
+}
+
+function cleanResponse(res: any): IClosestFacilityResponse {
+  // add "geoJson" property to "routes"
+  if (res.routes.spatialReference.wkid === 4326) {
+    res.routes.geoJson = arcgisToGeoJSON(res.routes);
+  }
+  return res;
+}
+
+export default {
+  closestFacility,
+};

package/packages/arcgis-rest-routing/src/helpers.ts

@@ -0,0 +1,104 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { IRequestOptions } from "@esri/arcgis-rest-request";
+import {
+  ILocation,
+  IPoint,
+  IPolyline,
+  Position2D,
+  IFeatureSet
+} from "@esri/arcgis-rest-types";
+
+// https always
+export const ARCGIS_ONLINE_ROUTING_URL =
+  "https://route.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World";
+export const ARCGIS_ONLINE_CLOSEST_FACILITY_URL =
+  "https://route.arcgis.com/arcgis/rest/services/World/ClosestFacility/NAServer/ClosestFacility_World";
+export const ARCGIS_ONLINE_SERVICE_AREA_URL =
+  "https://route.arcgis.com/arcgis/rest/services/World/ServiceAreas/NAServer/ServiceArea_World";
+export const ARCGIS_ONLINE_ORIGIN_DESTINATION_MATRIX_URL =
+  "https://route.arcgis.com/arcgis/rest/services/World/OriginDestinationCostMatrix/NAServer/OriginDestinationCostMatrix_World";
+
+// nice to have: verify custom endpoints contain 'NAServer' and end in a '/'
+export interface IEndpointOptions extends IRequestOptions {
+  /**
+   * Any ArcGIS Routing service (example: https://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Network/USA/NAServer/Route/ ) to use for the routing service request.
+   */
+  endpoint?: string;
+}
+
+function isLocationArray(
+  coords: ILocation | IPoint | [number, number] | [number, number, number]
+): coords is [number, number] | [number, number, number] {
+  return (
+    (coords as [number, number]).length === 2 ||
+    (coords as [number, number, number]).length === 3
+  );
+}
+
+function isLocation(
+  coords: ILocation | IPoint | [number, number] | [number, number, number]
+): coords is ILocation {
+  return (
+    (coords as ILocation).latitude !== undefined ||
+    (coords as ILocation).lat !== undefined
+  );
+}
+
+export function normalizeLocationsList(
+  locations: Array<IPoint | ILocation | [number, number]>
+): string[] {
+  return locations.map((coords) => {
+    if (isLocationArray(coords)) {
+      return coords.join();
+    } else if (isLocation(coords)) {
+      if (coords.lat) {
+        return coords.long + "," + coords.lat;
+      } else {
+        return coords.longitude + "," + coords.latitude;
+      }
+    } else {
+      return coords.x + "," + coords.y;
+    }
+  });
+}
+
+export function decompressGeometry(str: string) {
+  let xDiffPrev = 0;
+  let yDiffPrev = 0;
+  const points = [];
+  let x;
+  let y;
+
+  // Split the string into an array on the + and - characters
+  const strings = str.match(/((\+|-)[^+-]+)/g);
+
+  // The first value is the coefficient in base 32
+  const coefficient = parseInt(strings[0], 32);
+
+  for (let j = 1; j < strings.length; j += 2) {
+    // j is the offset for the x value
+    // Convert the value from base 32 and add the previous x value
+    x = parseInt(strings[j], 32) + xDiffPrev;
+    xDiffPrev = x;
+
+    // j+1 is the offset for the y value
+    // Convert the value from base 32 and add the previous y value
+    y = parseInt(strings[j + 1], 32) + yDiffPrev;
+    yDiffPrev = y;
+
+    points.push([x / coefficient, y / coefficient] as Position2D);
+  }
+
+  return {
+    paths: [points],
+  } as IPolyline;
+}
+
+/**
+ * User Defined Type Guard that verifies this is a featureSet
+ */
+export function isFeatureSet(arg: any): arg is IFeatureSet {
+  return Object.prototype.hasOwnProperty.call(arg, 'features');
+}

package/packages/arcgis-rest-routing/src/index.ts

@@ -0,0 +1,14 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+export * from "./solveRoute";
+export * from "./closestFacility";
+export * from "./serviceArea";
+export * from "./originDestinationMatrix";
+export * from "./helpers";
+export {
+  ILocation,
+  ISpatialReference,
+  IPoint,
+  IFeature,
+} from "@esri/arcgis-rest-types";

package/packages/arcgis-rest-routing/src/originDestinationMatrix.ts

@@ -0,0 +1,223 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import {
+  request,
+  cleanUrl,
+  appendCustomParams,
+  IRequestOptions,
+} from "@esri/arcgis-rest-request";
+
+import {
+  ILocation,
+  IPoint,
+  IFeature,
+  IFeatureSet,
+} from "@esri/arcgis-rest-types";
+
+import {
+  ARCGIS_ONLINE_ORIGIN_DESTINATION_MATRIX_URL,
+  IEndpointOptions,
+  normalizeLocationsList,
+  isFeatureSet,
+} from "./helpers";
+
+import { arcgisToGeoJSON } from "@terraformer/arcgis";
+
+export interface IOriginDestinationMatrixOptions extends IEndpointOptions {
+  /**
+   *  Specify the starting points from which to travel to the destinations.
+   */
+  origins: Array<IPoint | ILocation | [number, number]> | IFeatureSet;
+  /**
+   *  Specify the ending point locations to travel to from the origins.
+   */
+  destinations: Array<IPoint | ILocation | [number, number]> | IFeatureSet;
+  /**
+   *  Specify the type of output returned by the service. Defaults to "esriNAODOutputSparseMatrix".
+   */
+  outputType?:
+  | "esriNAODOutputSparseMatrix"
+  | "esriNAODOutputStraightLines"
+  | "esriNAODOutputNoLines";
+  barriers?: Array<IPoint | ILocation | [number, number]> | IFeatureSet;
+  polylineBarriers?: IFeatureSet;
+  polygonBarriers?: IFeatureSet;
+  returnOrigins?: boolean;
+  returnDestinations?: boolean;
+  returnBarriers?: boolean;
+  returnPolylineBarriers?: boolean;
+  returnPolygonBarriers?: boolean;
+}
+
+interface IFeatureSetWithGeoJson extends IFeatureSet {
+  geoJson?: any;
+}
+
+export interface IOriginDestinationMatrixResponse {
+  messages: { type: number, description: string }[];
+  /**
+   *  Only present if outputType is "esriNAODOutputSparseMatrix". Full description is available at https://developers.arcgis.com/rest/network/api-reference/origin-destination-cost-matrix-synchronous-service.htm#ESRI_SECTION2_114F8364507C4B56B780DFAD505270FB.
+   */
+  odCostMatrix?: any;
+  /**
+   *  Only present if outputType is "esriNAODOutputStraightLines" or "esriNAODOutputNoLines". Includes the geometry for the straight line connecting each origin-destination pair when the outputType is "esriNAODOutputStraightLines".
+   */
+  odLines?: IFeatureSetWithGeoJson;
+  origins?: IFeatureSetWithGeoJson;
+  destinations?: IFeatureSetWithGeoJson;
+  barriers?: IFeatureSetWithGeoJson;
+  polylineBarriers?: IFeatureSetWithGeoJson;
+  polygonBarriers?: IFeatureSetWithGeoJson;
+}
+
+/**
+ * ```js
+ * import { originDestinationMatrix } from '@esri/arcgis-rest-routing';
+ * //
+ * originDestinationMatrix({
+ *   origins: [
+ *     [-90.404302, 38.600621],
+ *     [-90.364293, 38.620427],
+ *   ],
+ *   destinations: [
+ *     [-90.444716, 38.635501],
+ *     [-90.311919, 38.633523],
+ *     [-90.451147, 38.581107]
+ *   ],
+ *   authentication
+ * })
+ *   .then(response) // => { ... }
+ * ```
+ * Used to create an origin-destination (OD) cost matrix from multiple origins to multiple destinations. See the [REST Documentation](https://developers.arcgis.com/rest/network/api-reference/origin-destination-cost-matrix-synchronous-service.htm) for more information.
+ *
+ * @param requestOptions Options to pass through to the routing service.
+ * @returns A Promise that will resolve with travel time and/or distance for each origin-destination pair. It returns either odLines or odCostMatrix for this information depending on the outputType you specify.
+ * @restlink https://developers.arcgis.com/rest/network/api-reference/origin-destination-cost-matrix-synchronous-service.htm
+ */
+export function originDestinationMatrix(
+  requestOptions: IOriginDestinationMatrixOptions
+): Promise<IOriginDestinationMatrixResponse> {
+  const endpoint =
+    requestOptions.endpoint || ARCGIS_ONLINE_ORIGIN_DESTINATION_MATRIX_URL;
+
+  requestOptions.params = {
+    outputType: "esriNAODOutputSparseMatrix",
+    returnOrigins: true,
+    returnDestinations: true,
+    returnBarriers: true,
+    returnPolylineBarriers: true,
+    returnPolygonBarriers: true,
+    ...requestOptions.params,
+  };
+
+  const options = appendCustomParams<IOriginDestinationMatrixOptions>(
+    requestOptions,
+    [
+      "outputType",
+      "barriers",
+      "polylineBarriers",
+      "polygonBarriers",
+      "returnOrigins",
+      "returnDestinations",
+      "returnBarriers",
+      "returnPolylineBarriers",
+      "returnPolygonBarriers",
+    ]
+  );
+
+  // the SAAS service does not support anonymous requests
+  if (
+    !requestOptions.authentication &&
+    endpoint === ARCGIS_ONLINE_ORIGIN_DESTINATION_MATRIX_URL
+  ) {
+    return Promise.reject(
+      "Calculating the origin-destination cost matrix using the ArcGIS service requires authentication"
+    );
+  }
+
+  // use a formatting helper for input params of this type: Array<IPoint | ILocation | [number, number]>
+  if (isFeatureSet(requestOptions.origins)) {
+    options.params.origins = requestOptions.origins;
+  } else {
+    options.params.origins = normalizeLocationsList(
+      requestOptions.origins
+    ).join(";");
+  }
+
+  if (isFeatureSet(requestOptions.destinations)) {
+    options.params.destinations = requestOptions.destinations;
+  } else {
+    options.params.destinations = normalizeLocationsList(
+      requestOptions.destinations
+    ).join(";");
+  }
+
+  // optional input param that may need point geometry normalizing
+  if (requestOptions.barriers) {
+    if (isFeatureSet(requestOptions.barriers)) {
+      options.params.barriers = requestOptions.barriers;
+    } else {
+      // optional point geometry barriers must be normalized, too
+      // but not if provided as IFeatureSet type
+      // note that optional polylineBarriers and polygonBarriers do not need to be normalized
+      options.params.barriers = normalizeLocationsList(
+        requestOptions.barriers
+      ).join(";");
+    }
+  }
+
+  return request(`${cleanUrl(endpoint)}/solveODCostMatrix`, options).then(
+    function (res) {
+      return cleanResponse(res, options);
+    }
+  );
+}
+
+function cleanResponse(
+  res: any,
+  options: IRequestOptions
+): IOriginDestinationMatrixResponse {
+  // add "geoJson" property to each response property that is an arcgis featureSet
+
+  // res.odLines only exists and only includes geometry in this condition (out of 3 possible options.params.outputType conditions)
+  if (
+    options.params.outputType === "esriNAODOutputStraightLines" &&
+    res.odLines &&
+    res.odLines.spatialReference.wkid === 4326
+  ) {
+    res.odLines.geoJson = arcgisToGeoJSON(res.odLines);
+  }
+
+  if (res.origins && res.origins.spatialReference.wkid === 4326) {
+    res.origins.geoJson = arcgisToGeoJSON(res.origins);
+  }
+
+  if (res.destinations && res.destinations.spatialReference.wkid === 4326) {
+    res.destinations.geoJson = arcgisToGeoJSON(res.destinations);
+  }
+
+  if (res.barriers && res.barriers.spatialReference.wkid === 4326) {
+    res.barriers.geoJson = arcgisToGeoJSON(res.barriers);
+  }
+
+  if (
+    res.polygonBarriers &&
+    res.polygonBarriers.spatialReference.wkid === 4326
+  ) {
+    res.polygonBarriers.geoJson = arcgisToGeoJSON(res.polygonBarriers);
+  }
+
+  if (
+    res.polylineBarriers &&
+    res.polylineBarriers.spatialReference.wkid === 4326
+  ) {
+    res.polylineBarriers.geoJson = arcgisToGeoJSON(res.polylineBarriers);
+  }
+
+  return res;
+}
+
+export default {
+  originDestinationMatrix,
+};