sintfacilis 1.0.0

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,
+};

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

@@ -0,0 +1,173 @@
+/* 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_SERVICE_AREA_URL,
+  IEndpointOptions,
+  normalizeLocationsList,
+  isFeatureSet,
+} from "./helpers";
+
+import { arcgisToGeoJSON } from "@terraformer/arcgis";
+
+export interface IServiceAreaOptions extends IEndpointOptions {
+  /**
+   *  Specify one or more locations around which service areas are generated.
+   */
+  facilities: Array<IPoint | ILocation | [number, number]> | IFeatureSet;
+  /**
+   *  Specify if the service should return routes.
+   */
+  travelDirection?: "incidentsToFacilities" | "facilitiesToIncidents";
+  barriers?: Array<IPoint | ILocation | [number, number]> | IFeatureSet;
+  polylineBarriers?: IFeatureSet;
+  polygonBarriers?: IFeatureSet;
+  outputLines?: boolean;
+  returnFacilities?: boolean;
+  returnBarriers?: boolean;
+  returnPolylineBarriers?: boolean;
+  returnPolygonBarriers?: boolean;
+  preserveObjectID?: boolean;
+}
+
+interface IFeatureSetWithGeoJson extends IFeatureSet {
+  geoJson?: any;
+}
+
+export interface IServiceAreaResponse {
+  messages: string[];
+  saPolygons?: IFeatureSetWithGeoJson;
+  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 { serviceArea } from '@esri/arcgis-rest-routing';
+ * //
+ * serviceArea({
+ *   facilities: [
+ *     [-90.444716, 38.635501],
+ *     [-90.311919, 38.633523],
+ *     [-90.451147, 38.581107]
+ *    ],
+ *    authentication
+ * })
+ *   .then(response) // => {routes: {features: [{attributes: { ... }, geometry:{ ... }}]}
+ * ```
+ * Used to find the area that can be reached from the input location within a given travel time or travel distance. See the [REST Documentation](https://developers.arcgis.com/rest/network/api-reference/service-area-synchronous-service.htm) for more information.
+ *
+ * @param requestOptions Options to pass through to the routing service.
+ * @returns A Promise that will resolve with service area polygons for the request.
+ * @restlink https://developers.arcgis.com/rest/network/api-reference/service-area-synchronous-service.htm
+ */
+export function serviceArea(
+  requestOptions: IServiceAreaOptions
+): Promise<IServiceAreaResponse> {
+  const endpoint = requestOptions.endpoint || ARCGIS_ONLINE_SERVICE_AREA_URL;
+
+  requestOptions.params = {
+    returnFacilities: true,
+    returnBarriers: true,
+    returnPolylineBarriers: true,
+    returnPolygonBarriers: true,
+    preserveObjectID: true,
+    ...requestOptions.params,
+  };
+
+  const options = appendCustomParams<IServiceAreaOptions>(requestOptions, [
+    "barriers",
+    "polylineBarriers",
+    "polygonBarriers",
+    "outputLines",
+    "returnFacilities",
+    "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_SERVICE_AREA_URL
+  ) {
+    return Promise.reject(
+      "Finding service areas using the ArcGIS service requires authentication"
+    );
+  }
+
+  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)}/solveServiceArea`, options).then(
+    cleanResponse
+  );
+}
+
+function cleanResponse(res: any): IServiceAreaResponse {
+  // remove "fieldAliases" because it does not do anything.
+  delete res.saPolygons.fieldAliases;
+
+  // add "geoJson" property to "saPolygons"
+  if (res.saPolygons.spatialReference.wkid === 4326) {
+    res.saPolygons.geoJson = arcgisToGeoJSON(res.saPolygons);
+  }
+  return res;
+}
+
+export default {
+  serviceArea,
+};

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

@@ -0,0 +1,180 @@
+/* Copyright (c) 2018 Environmental Systems Research Institute, Inc.
+ * Apache-2.0 */
+
+import { request, cleanUrl } from "@esri/arcgis-rest-request";
+
+import {
+  ILocation,
+  ISpatialReference,
+  IPoint,
+  IFeature,
+  IFeatureSet,
+} from "@esri/arcgis-rest-types";
+
+import {
+  ARCGIS_ONLINE_ROUTING_URL,
+  IEndpointOptions,
+  decompressGeometry,
+  isFeatureSet,
+} from "./helpers";
+
+import { arcgisToGeoJSON } from "@terraformer/arcgis";
+
+interface IFeatureWithCompressedGeometry extends IFeature {
+  compressedGeometry?: string;
+}
+
+interface IFeatureSetWithGeoJson extends IFeatureSet {
+  geoJson?: {};
+}
+
+export interface ISolveRouteOptions extends IEndpointOptions {
+  /**
+   * Specify two or more locations between which the route is to be found.
+   */
+  stops:
+    | Array<IPoint | ILocation | [number, number] | [number, number, number]>
+    | IFeatureSet;
+}
+
+export interface ISolveRouteResponse {
+  messages: string[];
+  checksum: string;
+  routes: IFeatureSetWithGeoJson;
+  directions?: Array<{
+    routeId: number;
+    routeName: string;
+    summary: object;
+    features: IFeature[];
+  }>;
+}
+
+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
+  );
+}
+
+/**
+ * ```js
+ * import { solveRoute } from '@esri/arcgis-rest-routing';
+ * //
+ * solveRoute({
+ *   stops: [
+ *     [-117.195677, 34.056383],
+ *     [-117.918976, 33.812092],
+ *    ],
+ *    authentication
+ * })
+ *   .then(response) // => {routes: {features: [{attributes: { ... }, geometry:{ ... }}]}
+ * ```
+ * Used to find the best way to get from one location to another or to visit several locations. See the [REST Documentation](https://developers.arcgis.com/rest/network/api-reference/route-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/route-synchronous-service.htm
+ */
+export function solveRoute(
+  requestOptions: ISolveRouteOptions
+): Promise<ISolveRouteResponse> {
+  const options: ISolveRouteOptions = {
+    endpoint: requestOptions.endpoint || ARCGIS_ONLINE_ROUTING_URL,
+    params: {},
+    ...requestOptions,
+  };
+
+  // the SAAS service does not support anonymous requests
+  if (
+    !requestOptions.authentication &&
+    options.endpoint === ARCGIS_ONLINE_ROUTING_URL
+  ) {
+    return Promise.reject(
+      "Routing using the ArcGIS service requires authentication"
+    );
+  }
+
+  if (isFeatureSet(requestOptions.stops)) {
+    options.params.stops = requestOptions.stops;
+  } else {
+    const stops: string[] = requestOptions.stops.map((coords) => {
+      if (isLocationArray(coords)) {
+        return coords.join();
+      } else if (isLocation(coords)) {
+        if (coords.lat) {
+          return (
+            coords.long + "," + coords.lat + (coords.z ? "," + coords.z : "")
+          );
+        } else {
+          return (
+            coords.longitude +
+            "," +
+            coords.latitude +
+            (coords.z ? "," + coords.z : "")
+          );
+        }
+      } else {
+        return coords.x + "," + coords.y + (coords.z ? "," + coords.z : "");
+      }
+    });
+
+    options.params.stops = stops.join(";");
+  }
+
+  return request(`${cleanUrl(options.endpoint)}/solve`, options).then(
+    cleanResponse
+  );
+}
+
+function cleanResponse(res: any): ISolveRouteResponse {
+  if (res.directions && res.directions.length > 0) {
+    res.directions = res.directions.map(
+      (direction: {
+        features: IFeatureWithCompressedGeometry[];
+        routeId: number;
+        routeName: string;
+        summary: {};
+      }) => {
+        direction.features = direction.features.map(
+          (feature: IFeatureWithCompressedGeometry) => {
+            feature.geometry = decompressGeometry(feature.compressedGeometry);
+            return feature;
+          }
+        );
+        return direction;
+      }
+    );
+  }
+
+  // add "geoJson" property to "routes"
+  if (res.routes.spatialReference.wkid === 4326) {
+    const features = res.routes.features.map((feature: any) => {
+      return {
+        type: "Feature",
+        geometry: arcgisToGeoJSON(feature.geometry),
+        properties: Object.assign({}, feature.attributes),
+      };
+    });
+
+    res.routes.geoJson = {
+      type: "FeatureCollection",
+      features,
+    };
+  }
+  return res;
+}
+
+export default {
+  solveRoute,
+};