Origin Destination Cost Matrix service with asynchronous execution

Attributes for origins

When specifying the origins, you can set properties for each—such as its name or the number of destinations to find from the origin— using the following attributes:

• Name

  The name of the origin. The name can be a unique identifier for the origin. The name is included in the output lines (as the OriginName field) and in the output origins (as the Name field) and can be used to join additional information from the tool outputs to the attributes of your origins.

  If the name is not specified, a unique name prefixed with Location is automatically generated.

• TargetDestinationCount

  The maximum number of destinations to find for the origin.

  If a value is not specified, the value from the Number of Destinations to Find parameter is used.

  This field allows you to specify a different number of destinations to find for each origin. For example, using this field, you can find the three closest destinations from one origin and the two closest destinations from another origin.

• Cutoff

  The impedance value at which to stop searching for destinations from a given origin. This attribute allows you to specify a different cutoff value for each destination. For example, using this attribute, you can specify to search for destinations within five minutes of travel time from one origin and to search for destinations within eight minutes of travel time from another origin.

  The units of the cutoff are the same as the units of your impedance attribute. If a value is not specified, the value from the Cutoff parameter is used.

• CurbApproach

  Specifies the direction a vehicle may depart from the origin. One of the integers listed in the Coded value column in the following table must be specified as a value of this attribute. The values in the Setting column are the descriptive names for CurbApproach attribute values that you may have seen when using the ArcGIS Network Analyst extension software.

  Setting	Coded value	Description
  Either side of vehicle	0	The vehicle can depart the origin in either direction, so a U-turn is allowed at the origin. This setting can be chosen if it is possible and practical for your vehicle to turn around at the origin. This decision may depend on the width of the road and the amount of traffic or whether the origin has a parking lot where vehicles can enter and turn around. Departing the origin so that it is on the right side of the vehicle is allowed. Departing the origin so that it is on the left side of the vehicle is allowed.
  Right side of vehicle	1	When the vehicle departs the origin, the origin must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must depart from the bus stop on the right side. Departing the origin so that it is on the right side of the vehicle is allowed.
  Left side of vehicle	2	When the vehicle departs the origin, the origin must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must depart from the bus stop on the left side. Departing the origin so that it is on the left side of the vehicle is allowed.

  The CurbApproach attribute is designed to work with both types of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider an incident on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach an incident from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, if you want to arrive at an incident and not have a lane of traffic between the vehicle and the incident, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

  With right-hand traffic, the curb approach that leaves the vehicle closest to the origin is Right side of vehicle.

  With left-hand traffic, the curb approach that leaves the vehicle closest to the origin is Left side of vehicle.

• Bearing

  The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

  Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

  Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

  Learn more about bearing and bearing tolerance

• BearingTol

  The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the value from the Bearing field is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

  The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

  Learn more about bearing and bearing tolerance

• NavLatency

  This field is only used in the solve process if Bearing and BearingTol also have values; however, entering a NavLatency value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much time is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

  The time units of NavLatency are the same as the units specified by the timeUnits property of the analysis object.

Syntax examples for origins

Syntax for specifying origins using a JSON structure for features

{
  "spatialReference": {
    "wkid": <wkid>,
    "latestWkid": <wkid>
  },
  "features": [
    {
      "geometry": {
        "x": <x1>,
        "y": <y1>
      },
      "attributes": {
        "<field1>": <value1_1>,
        "<field2>": <value1_2>
      }
    },
    {
      "geometry": {
        "x": <x2>,
        "y": <y2>
      },
      "attributes": {
        "<field1>": <value2_1>,
        "<field2>": <value2_2>
      }
    }
  ]
}

Syntax for specifying origins using a URL returning a JSON response

{
  "url": "<url>"
}

Examples for origins

Example one: Specifying origins in the same spatial reference as the network dataset, WGS84, using JSON structure

The origin geometries are in the same spatial reference as the network dataset, WGS84. Hence, the spatialReference property is not specified. The example also shows how to specify some attributes for the origins.

{
  "features": [
    {
      "geometry": {
        "y": 51.5254,
        "x": -0.1891
      },
      "attributes": {
        "Name": "Origin 1",
        "TargetDestinationCount": 50, 
        "Cutoff": 120,
        "CurbApproach": 0
      }
    },
    {
      "geometry": {
        "y": 51.5353,
        "x": -0.1744
      },
      "attributes": {
        "Name": "Origin 2",
        "TargetDestinationCount": 40,
        "Cutoff": 90,
        "CurbApproach": 0
      }
    }
  ]
}

Example two: Specifying origins in the Web Mercator spatial reference using a JSON structure

The origin geometries are in the Web Mercator spatial reference and not in the spatial reference as the network dataset. Hence, the spatialReference property is required.

{
  "spatialReference": {
    "wkid": 102100
  },
  "features": [
    {
      "geometry": {
        "y": -5192521.476,
        "x": -2698533.989
      },
      "attributes": {
        "Name": "Origin 1"
      }
    },
    {
      "geometry": {
        "y": -5191915.261,
        "x": -2697821.094
      },
      "attributes": {
        "Name": "Origin 2"
      }
    }
  ]
}

Example three: Specifying origins using URL

The URL makes a query for a few features from a map service. A URL querying features from a feature service can also be specified.

{
  "url": "https://machine.domain.com/webadaptor/rest/services/NetworkAnalysis/SanDiego/MapServer/21/query?where=1%3D1&outFields=Name&f=json"
}

Attributes for destinations

When specifying the destinations, you can set properties for each—such as its name—using the following attributes:

• Name

  The name of the destination. The name can be a unique identifier for the destination. The name is included in the output lines (as the DestinationName field) and in the output destinations (as the Name field) and can be used to join additional information from the tool outputs to the attributes of your destinations.

  If the name is not specified, a unique name prefixed with Location is automatically generated.

• CurbApproach

  Specifies the direction a vehicle may arrive at the destination. One of the integers listed in the Coded value column in the following table must be specified as a value of this attribute. The values in the Setting column are the descriptive names for CurbApproach attribute values that you may have seen when using ArcGIS Network Analyst extension software.

  Setting	Coded value	Description
  Either side of vehicle	0	The vehicle can arrive at the destination from either direction. This setting can be chosen if it is possible and practical for your vehicle to turn around at the destination. This decision may depend on the width of the road and the amount of traffic or whether the destination has a parking lot where vehicles can enter and turn around. Approaching the destination so that it is on the right side of the vehicle is allowed. Approaching the destination so that it is on the left side of the vehicle is allowed.
  Right side of vehicle	1	When the vehicle arrives at the destination, the destination must be on the right side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive at the bus stop on the right side. Approaching the destination so that it is on the right side of the vehicle is allowed.
  Left side of vehicle	2	When the vehicle arrives at the destination, the destination must be on the left side of the vehicle. A U-turn is prohibited. This is typically used for vehicles such as buses that must arrive at the bus stop on the left side. Approaching the destination so that it is on the right side of the vehicle is allowed.

  The CurbApproach attribute is designed to work with both types of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider an incident on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach an incident from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, if you want to arrive at an incident and not have a lane of traffic between the vehicle and the incident, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

  With right-hand traffic, the curb approach that leaves the vehicle closest to the destination is Right side of vehicle.

  With left-hand traffic, the curb approach that leaves the vehicle closest to the destination is Left side of vehicle.

• Bearing

  The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

  Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

  Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

  Learn more about bearing and bearing tolerance

• BearingTol

  The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the value from the Bearing field is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

  The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

  Learn more about bearing and bearing tolerance

• NavLatency

  This field is only used in the solve process if Bearing and BearingTol also have values; however, entering a NavLatency value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much time is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

  The time units of NavLatency are the same as the units specified by the timeUnits property of the analysis object.

Syntax examples for destinations

Syntax for specifying destinations using a JSON structure for features

{
  "spatialReference": {
    "wkid": <wkid>,
    "latestWkid": <wkid>
  },
  "features": [
    {
      "geometry": {
        "x": <x1>,
        "y": <y1>
      },
      "attributes": {
        "<field1>": <value1_1>,
        "<field2>": <value1_2>
      }
    },
    {
      "geometry": {
        "x": <x2>,
        "y": <y2>
      },
      "attributes": {
        "<field1>": <value2_1>,
        "<field2>": <value2_2>
      }
    }
  ] 
}

Syntax for specifying destinations using a URL returning a JSON response

{
  "url": "<url>"
}

Examples for destinations

Example one: Specifying destinations in the same spatial reference as the network dataset, using JSON structure

The destination geometries are in the same spatial reference as the network dataset. Hence, the spatialReference property is not specified. The example also shows how to specify some attributes for the destinations.

{
  "features": [
    {
      "geometry": {
        "y": 51.5354,
        "x": -0.1991
      },
      "attributes": {
        "Name": "Destination 1",
        "CurbApproach": 0
      }
    },
    {
      "geometry": {
        "y": 51.5458,
        "x": -0.1844
      },
      "attributes": {
        "Name": "Destination 2",
        "CurbApproach": 0
      }
    }
  ]
}

Example two: Specifying destinations in the Web Mercator spatial reference using a JSON structure

The destination geometries are in the Web Mercator spatial reference and not in the spatial reference of the network dataset. Hence, the spatialReference property is required.

{
  "spatialReference": {
    "wkid": 102100
  },
  "features": [
    {
      "geometry": {
        "y": -5182521.476,
        "x": -2688533.989
      },
      "attributes": {
        "Name": "Destination 1"
      }
    },
    {
      "geometry": {
        "y": -5201915.261,
        "x": -2717821.094
      },
      "attributes": {
        "Name": "Destination 2"
      }
    }
  ]
}

Example three: Specifying origins using a URL

The URL makes a query for a few features from a map service. A URL querying features from a feature service can also be specified.

{
  "url": "https://machine.domain.com/webadaptor/rest/services/NetworkAnalysis/SanDiego/MapServer/21/query?where=1%3D1&outFields=Name&f=json"
}

Geographically Local

The Geographically Local value indicates for the service to use the time zone in which the input origins are geographically located when applying the time_of_day value.

UTC

The timeOfDay value refers to UTC. The UTC value indicates for the service to use UTC as the time zone when applying the time_of_day value.

Note:

This parameter is ignored when travel_mode is distance based or the impedance parameter is set to Travel Distance if you're using a custom travel mode.

Attributes for point_barriers

When specifying point barriers, you can set properties for each, such as its name or barrier type, using the following attributes:

• Name

  The name of the barrier.

• BarrierType

  Specifies whether the point barrier restricts travel completely or adds time or distance when it is crossed. The value for this attribute is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Restriction)—Prohibits travel through the barrier. The barrier is referred to as a restriction point barrier since it acts as a restriction.

    The map on the left shows the shortest path between two stops without any restriction point barriers. The map on the right has a road that is blocked by a fallen tree, so the shortest path between the same points is longer.

  • 2 (Added Cost)—Traveling through the barrier increases the travel time or distance by the amount specified in the Additional_Time, Additional_Distance, or Additional_Cost field. This barrier type is referred to as an added-cost point barrier.

    The map on the left shows the shortest path between two stops without any added-cost point barrier. For the map on the right, the travel time from stop one to stop two would be the same whether going around the north end of the block or the south end; however, since crossing railroad tracks incurs a time penalty (modeled with added-cost point barriers), the route with only one railroad crossing is chosen. The cost of crossing the barrier is added to the accumulated travel time of the resulting route.

• Additional_Time

  The added travel time when the barrier is traversed. This field is applicable only for added-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is time based.

  This field value must be greater than or equal to zero, and its units are the same as those specified in the Measurement Units parameter.

• Additional_Distance

  The added distance when the barrier is traversed. This field is applicable only for added-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is distance based.

  The field value must be greater than or equal to zero, and its units are the same as those specified in the Measurement Units parameter.

• Additional_Cost

  The added cost when the barrier is traversed. This field is applicable only for added-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is neither time based nor distance based.

• FullEdge

  Specifies how the restriction point barriers are applied to the edge elements during the analysis. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (False)—Permits travel on the edge up to the barrier but not through it. This is the default value.
  • 1 (True)—Restricts travel anywhere on the associated edge.

• CurbApproach

  Specifies the direction of traffic that is affected by the barrier. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Either side of vehicle)—The barrier affects travel over the edge in both directions.
  • 1 (Right side of vehicle)—Vehicles are only affected if the barrier is on their right side during the approach. Vehicles that traverse the same edge but approach the barrier on their left side are not affected by the barrier.
  • 2 (Left side of vehicle)—Vehicles are only affected if the barrier is on their left side during the approach. Vehicles that traverse the same edge but approach the barrier on their right side are not affected by the barrier.

  Because junctions are points and don't have a side, barriers on junctions affect all vehicles regardless of the curb approach.

  The CurbApproach attribute is designed to work with both types of national driving standards: right-hand traffic (United States) and left-hand traffic (United Kingdom). First, consider a facility on the left side of a vehicle. It is always on the left side regardless of whether the vehicle travels on the left or right half of the road. What may change with national driving standards is your decision to approach a facility from one of two directions, that is, so it ends up on the right or left side of the vehicle. For example, if you want to arrive at a facility and not have a lane of traffic between the vehicle and the facility, choose 1 (Right side of vehicle) in the United States and 2 (Left side of vehicle) in the United Kingdom.

• Bearing

  The direction in which a point is moving. The units are degrees and are measured clockwise from true north. This field is used in conjunction with the BearingTol field.

  Bearing data is usually sent automatically from a mobile device equipped with a GPS receiver. Try to include bearing data if you are loading an input location that is moving, such as a pedestrian or a vehicle.

  Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps the tool determine on which side of the street the point is.

  Learn more about bearing and bearing tolerance

• BearingTol

  The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the value from the Bearing field is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

  The units are in degrees, and the default value is 30. Values must be greater than 0 and less than 180. A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15 degrees to either side of the edge (left and right) and in both digitized directions of the edge.

  Learn more about bearing and bearing tolerance

• NavLatency

  This field is only used in the solve process if Bearing and BearingTol also have values; however, entering a NavLatency value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much time is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device.

  The time units of NavLatency are the same as the units specified by the timeUnits property of the analysis object.

Syntax examples for point_barriers

Syntax for specifying point_barriers using a JSON structure for features

{
  "spatialReference": {
    "wkid": <wkid>,
    "latestWkid": <wkid>
  },
  "features": [
    {
      "geometry": {
        "x": <x1>,
        "y": <y1>
      },
      "attributes": {
        "<field1>": <value11>,
        "<field2>": <value12>
      }
    },
    {
      "geometry": {
        "x": <x2>,
        "y": <y2>
      },
      "attributes": {
        "<field1>": <value21>,
        "<field2>": <value22>
      }
    }
  ] 
}

Syntax for specifying point_barriers using a URL returning a JSON response

{
  "url": "<url>"
}

Examples for point_barriers

Example one: Specifying an added-cost point barrier in the same spatial reference as the network dataset, using JSON structure

This example shows how to use an added-cost point barrier to model a 5-minute delay at a railroad crossing. The BarrierType attribute is used to specify the point barrier is of type added cost and the Additional_Time attribute is used to specify the added delay in minutes. The barrier geometries are in the same spatial reference as the network dataset. Hence, the spatialReference property is not specified.

{
  "features": [
    {
      "geometry": {
        "x": 37.541479,
        "y": -122.053461
      },
      "attributes": {
        "Name": "Haley St railroad crossing",
        "BarrrierType": 2,
        "Additional_Time": 5
      }
    }
  ]
}

Example two: Specifying restriction point barriers in the Web Mercator spatial reference using a JSON structure

This example shows how to use a restriction point barrier to model a road that is blocked by a fallen tree. The barrier's geometry is in the Web Mercator spatial reference and not in the same spatial reference as the network dataset. Hence, the spatialReference property is required.

{
  "spatialReference": {
    "wkid": 102100
  },
  "features": [
    {
      "geometry": {
        "y": -13635398.9398,
        "x": 4544699.034400001
      },
      "attributes": {
        "Name": "Fallen tree at 123 Main St", 
        "BarrierType": 0
      }
    }
  ]
}

Example three: Specifying point barriers using a URL

The URL makes a query for a few features from a map service. A URL querying features from a feature service can also be specified.

{
  "url": "https://machine.domain.com/webadaptor/rest/services/NetworkAnalysis/SanDiego/MapServer/21/query?where=1%3D1&outFields=Name&f=json"
}

Attributes for line_barriers

When specifying the line barriers, you can set name and barrier type properties for each using the following attributes:

• Name

  The name of the barrier.

Syntax examples for line_barriers

Syntax for specifying line barriers using a JSON structure for features

{
  "spatialReference": {
    "wkid": <wkid>,
    "latestWkid": <wkid>
  },
  "features": [
    {
      "geometry": {
        "paths": [
          [
            [
              <x11>,
              <y11>
            ],
            [
              <x12>,
              <y12>
            ]
          ],
          [
            [
              <x21>,
              <y21>
            ],
            [
              <x22>,
              <y22>
            ]
          ]
        ]
      },
      "attributes": {
        "<field1>": <value11>,
        "<field2>": <value12>
      }
    },
		  {
      "geometry": {
        "paths": [
          [
            [
              <x11>,
              <y11>
            ],
            [
              <x12>,
              <y12>
            ]
          ],
          [
            [
              <x21>,
              <y21>
            ],
            [
              <x22>,
              <y22>
            ]
          ]
        ]
      },
      "attributes": {
        "<field1>": <value21>,
        "<field2>": <value22>
      }
    }
  ] 
}

Syntax for specifying line barriers using a URL returning a JSON response

{
  "url": "<url>"
}

Examples for line_barriers

Example one: Specifying line barriers using a JSON structure in the Web Mercator spatial reference

The example shows how to add two lines as line barriers to restrict travel on the streets intersected by the lines. Barrier 1 is a single-part line feature made up of two points. Barrier 2 is a two-part line feature whose first part is made up of three points and whose second part is made up of two points. The barrier geometries are in the Web Mercator spatial reference and not in the same spatial reference as the network dataset. Hence, the spatialReference property is required.

{
  "spatialReference": {
    "wkid": 102100
  },
  "features": [
    {
      "geometry": {
        "paths": [
          [
            [
              -10804823.397,
              3873688.372
            ],
            [
              -10804811.152,
              3873025.945
            ]
          ]
        ]
      },
      "attributes": {
        "Name": "Barrier 1"
      }
    },
    {
      "geometry": {
        "paths": [
          [
            [
              -10804823.397,
              3873688.372
            ],
            [
              -10804807.813,
              3873290.911
            ],
            [
              -10804811.152,
              3873025.945
            ]
          ],
          [
            [
              -10805032.678,
              3863358.76
            ],
            [
              -10805001.508,
              3862829.281
            ]
          ]
        ]
      },
      "attributes": {
        "Name": "Barrier 2"
      }
    }
  ]
}

Example two: Specifying line barriers using a URL

The URL makes a query for a few features from a map service. A URL querying features from a feature service can also be specified.

{
  "url": "https://machine.domain.com/webadaptor/rest/services/Network/USA/MapServer/6/query?where=1%3D1&returnGeometry=true&f=json"
}

Attributes for polygon_barriers

When specifying the polygon barriers, you can set properties for each, such as its name or barrier type, using the following attributes:

• Name

  The name of the barrier.

• BarrierType

  Specifies whether the barrier restricts travel completely or scales the cost (such as time or distance) for traveling through it. The field value is specified as one of the following integers (use the numeric code, not the name in parentheses):

  • 0 (Restriction)—Prohibits traveling through any part of the barrier. The barrier is referred to as a restriction polygon barrier since it prohibits traveling on streets intersected by the barrier. One use of this type of barrier is to model floods covering areas of the street that make traveling on those streets impossible.

    The left side depicts the shortest path between two stops. On the right, a polygon barrier blocks flooded streets, so the shortest path between the same two stops is different.

  • 1 (Scaled Cost)—Scales the time or distance required to travel the underlying streets by a factor specified using the ScaledTimeFactor or ScaledDistanceFactor field. If the streets are partially covered by the barrier, the travel time or distance is apportioned and then scaled. For example, a factor of 0.25 would mean that travel on underlying streets is expected to be four times faster than normal. A factor of 3.0 would mean it is expected to take three times longer than normal to travel on underlying streets. This barrier type is referred to as a scaled-cost polygon barrier. It might be used to model storms that reduce travel speeds in specific regions.

    The map on the left shows a route that goes through inclement weather without regard for the effect that poor road conditions have on travel time. On the right, a scaled polygon barrier doubles the travel time of the roads covered by the storm. Notice the route still passes through the southern tip of the storm since it's quicker to spend more time driving slowly through a small part of the storm rather than driving completely around it. The service uses the modified travel time in calculating the best route; furthermore, the modified travel time is reported as the total travel time in the response.

• ScaledTimeFactor

  This is the factor by which the travel time of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

  This field is applicable only for scaled-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is time based.

• ScaledDistanceFactor

  This is the factor by which the distance of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

  This field is applicable only for scaled-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is distance based.

• ScaledCostFactor

  This is the factor by which the cost of the streets intersected by the barrier is multiplied. The field value must be greater than zero.

  This field is applicable only for scaled-cost barriers and only if the travel mode used for the analysis uses an impedance attribute that is neither time based nor distance based.

Syntax examples for polygon_barriers

Syntax for specifying polygon barriers using a JSON structure for features

{
  "spatialReference": {
    "wkid": <wkid>,
    "latestWkid": <wkid>    
  }
  "features": [
    {
      "geometry": {
        "rings": [
          [
            [
              <x11>,
              <y11>
            ],
            [
              <x12>,
              <y12>
            ],
            [
              <x11>,
              <y11>
            ]
          ],
          [
            [
              <x21>,
              <y21>
            ],
            [
              <x22>,
              <y22>
            ],
            [
              <x21>,
              <y21>
            ]
          ]
        ]
      },
      "attributes": {
        "<field1>": <value11>,
        "<field2>": <value12>
      }
    },
    {
      "geometry": {
        "rings": [
          [
            [
              <x11>,
              <y11>
            ],
            [
              <x12>,
              <y12>
            ],
            [
              <x11>,
              <y11>
            ]
          ],
          [
            [
              <x21>,
              <y21>
            ],
            [
              <x22>,
              <y22>
            ],
            [
              <x21>,
              <y21>
            ]
          ]
        ]
      },
      "attributes": {
        "<field1>": <value21>,
        "<field2>": <value22>
      }
    }
  ]
}

Syntax for specifying polygon barriers using a URL returning a JSON response

{
  "url": "<url>"
}

Examples for polygon_barriers

Example one: Specifying polygon barriers using a JSON structure

The example shows how to add two polygons as barriers. The first polygon, named Flood zone, is a restriction polygon barrier that prohibits travel on the underlying streets. The polygon is a single-part polygon feature made up of four points. The second polygon, named Severe weather zone, is a scaled-cost polygon barrier that increases the travel time on underlying streets to one-third of the original value. The polygon is a two-part polygon feature. Both parts are made up of four points.

The barrier geometries are in the same spatial reference as your network dataset. Hence, the spatialReference property is not required.

{
  "features": [
    {
      "geometry": {
        "rings": [
          [
            [
              -97.0634,
              32.8442
            ],
            [
              -97.0554,
              32.84
            ],
            [
              -97.0558,
              32.8327
            ],
            [
              -97.0638,
              32.83
            ],
            [
              -97.0634,
              32.8442
            ]
          ]
        ]
      },
      "attributes": {
        "Name": "Flood zone",
        "BarrierType": 0
      }
    },
    {
      "geometry": {
        "rings": [
          [
            [
              -97.0803,
              32.8235
            ],
            [
              -97.0776,
              32.8277
            ],
            [
              -97.074,
              32.8254
            ],
            [
              -97.0767,
              32.8227
            ],
            [
              -97.0803,
              32.8235
            ]
          ],
          [
            [
              -97.0871,
              32.8311
            ],
            [
              -97.0831,
              32.8292
            ],
            [
              -97.0853,
              32.8259
            ],
            [
              -97.0892,
              32.8279
            ],
            [
              -97.0871,
              32.8311
            ]
          ]
        ]
      },
      "attributes": {
        "Name": "Severe weather zone",
        "BarrierType": 1,
        "ScaledTimeFactor": 3
      }
    }
  ]
}

Example two: Specifying a polygon barrier using a URL

The URL makes a query for a few features from a map service. A URL querying features from a feature service can also be specified.

{
  "url": "https://machine.domain.com/webadaptor/rest/services/Network/USA/MapServer/7/query?where=1%3D1&returnGeometry=true&f=json"
}

Example for restrictions

restrictions=[Driving a Truck,Height Restriction,Length Restriction]

Attributes for attribute_parameter_values

The attribute_parameter_values parameter can be specified with the following attributes:

• AttributeName: Lists the name of the restriction.
• ParameterName: Lists the name of the parameter associated with the restriction. A restriction can have one or more ParameterName values based on its intended use, which implies you may need multiple attribute_parameter_values parameters for a single attribute name.
• ParameterValue: The value for the ParameterName that is used by the service when evaluating the restriction.

Note:

In most cases, the attribute_parameter_values parameter is dependent on the restrictions parameter. The ParameterValue specified as part of attribute_parameter_values is applicable only if the restriction name is specified as the value for the restrictions parameter.

When specifying the attribute_parameter_values parameter, each restriction (listed as AttributeName) has a ParameterName value, Restriction Usage, that specifies whether the restriction prohibits, avoids, or prefers travel on the roads associated with the restriction and the degree to which the roads are avoided or preferred.

The Restriction Usage ParameterName can be assigned any of the following string values or their equivalent numeric values listed within the parentheses:

• PROHIBITED (-1)—Travel on the roads using the restriction is completely prohibited.
• AVOID_HIGH (5)—It is very unlikely for the service to include, in the results, roads that are associated with the restriction.
• AVOID_MEDIUM (2)—It is unlikely for the service to include, in the results, roads that are associated with the restriction.
• AVOID_LOW (1.3)—It is somewhat unlikely for the service to include, in the results, roads that are associated with the restriction.
• PREFER_LOW (0.8)—It is somewhat likely for the service to include, in the results, results roads that are associated with the restriction.
• PREFER_MEDIUM(0.5)—It is likely for the service to include, in the results, roads that are associated with the restriction.
• PREFER_HIGH (0.2)—It is very likely for the service to include, in the results, roads that are associated with the restriction.

In most cases, you can use the default value, PROHIBITED, for Restriction Usage if the restriction is dependent on a physical vehicle characteristic, such as vehicle height. However, in some cases, the value for Restriction Usage depends on your travel preferences. For example, the Avoid Toll Roads restriction has the default value of AVOID_MEDIUM for the Restriction Usage parameter. This means that when the restriction is used, the service will try to route around toll roads when it can. AVOID_MEDIUM also indicates how important it is to avoid toll roads when finding the best route; it has a medium priority. Choosing AVOID_LOW would put lower importance on avoiding tolls; choosing AVOID_HIGH instead would give it a higher importance and thus make it more acceptable for the service to generate longer routes to avoid tolls. Choosing PROHIBITED would entirely disallow travel on toll roads, making it impossible for a route to travel on any portion of a toll road. Keep in mind that avoiding or prohibiting toll roads, and thus avoiding toll payments, is the objective for some; in contrast, others prefer to drive on toll roads because avoiding traffic is more valuable to them than the money spent on tolls. In the latter case, you would choose PREFER_LOW, PREFER_MEDIUM, or PREFER_HIGH as the value for Restriction Usage. The higher the preference, the farther the service will go out of its way to travel on the roads associated with the restriction.

The following table lists the restriction names and the default restriction parameter values for all the restrictions. The default value for the attribute_parameter_values parameter is the JSON structure containing all the rows from the below table.

Tip:

If you want to use the default value for any restriction, AttributeName, ParameterName, and ParameterValue do not have to be specified as part of the attribute_parameter_values parameter.

Syntax example for attribute_parameter_values

{
    "features": [
        {
            "attributes": {
                "<field1>": <value11>,
                "<field2>": <value12>,
                "<field3>": <value13>

            }
        },
        {
            "attributes": {
                "<field1>": <value21>,
                "<field2>": <value22>,
                "<field3>": <value13>
            }
        }
    ] 
}

Example for attribute_parameter_values

attribute_parameter_values=
{
    "features": [
        {
            "attributes": {
                "AttributeName": "Height Restriction",
                "ParameterName": "Vehicle Height (meters)",
                "ParameterValue": 4.12
            }
        },
        {
            "attributes": {
                "AttributeName": "Weight Restriction",
                "ParameterName": "Vehicle Weight (kilograms)",
                "ParameterValue": 36287
            }
        },
        {
            "attributes": {
                "AttributeName": "Use Preferred Truck Routes",
                "ParameterName": "Restriction Usage",
                "ParameterValue": "PREFER_HIGH"
            }
        }
    ]
}

Request to submit job

The first request submits a job and returns the job ID.

https://<gpservice-url>/GenerateOriginDestinationCostMatrix/submitJob?origins={"features":[{"geometry":{"y":51.5254,"x":-0.1891},"attributes":{"Name":"Origin 1","TargetDestinationCount":2,"Cutoff":120,"CurbApproach":0}},{"geometry":{"y":51.5353,"x":-0.1744},"attributes":{"Name":"Origin 2","TargetDestinationCount":3,"Cutoff":90,"CurbApproach":0}}]}&destinations={"features":[{"geometry":{"y":51.5354,"x":-0.1991},"attributes":{"Name":"Destination 1","CurbApproach":0}},{"geometry":{"y":51.5458,"x":-0.1844},"attributes":{"Name":"Destination 2","CurbApproach":0}}]}&f=pjson&token=<yourToken>

https://<gpservice-url>/GenerateOriginDestinationCostMatrix/submitJob?origins=%7B%22features%22:%5B%7B%22geometry%22:%7B%22y%22:51.5254,%22x%22:-0.1891%7D,%22attributes%22:%7B%22Name%22:%22Origin%201%22,%22TargetDestinationCount%22:2,%22Cutoff%22:120,%22CurbApproach%22:0%7D%7D,%7B%22geometry%22:%7B%22y%22:51.5353,%22x%22:-0.1744%7D,%22attributes%22:%7B%22Name%22:%22Origin%202%22,%22TargetDestinationCount%22:3,%22Cutoff%22:90,%22CurbApproach%22:0%7D%7D%5D%7D&destinations=%7B%22features%22:%5B%7B%22geometry%22:%7B%22y%22:51.5354,%22x%22:-0.1991%7D,%22attributes%22:%7B%22Name%22:%22Destination%201%22,%22CurbApproach%22:0%7D%7D,%7B%22geometry%22:%7B%22y%22:51.5458,%22x%22:-0.1844%7D,%22attributes%22:%7B%22Name%22:%22Destination%202%22,%22CurbApproach%22:0%7D%7D%5D%7D&f=pjson&token=<yourToken>

JSON Response

{
  "jobId": "j5943d41e8b2c4de7a0aaca3283655a33",
  "jobStatus": "esriJobSubmitted"
}

Request to query job status

https://<gpservice-url>/GenerateOriginDestinationCostMatrix/jobs/<jobID>?returnMessages=true&f=pjson&token=<yourToken>

https://<gpservice-url>/GenerateOriginDestinationCostMatrix/jobs/<jobID>?returnMessages=true&f=pjson&token=<yourToken>

JSON Response

{
  "jobId": "j5943d41e8b2c4de7a0aaca3283655a33",
  "jobStatus": "esriJobSucceeded",
  "results": {
    "Solve_Succeeded": {
      "paramUrl": "results/Solve_Succeeded"
    },
    "Output_Origin_Destination_Lines": {
      "paramUrl": "results/Output_Origin_Destination_Lines"
    },
    "Output_Origins": {
      "paramUrl": "results/Output_Origins"
    },
    "Output_Destinations": {
      "paramUrl": "results/Output_Destinations"
    }
  },
  "inputs": {
    "Origins": {
      "paramUrl": "inputs/Origins"
    },
    "Destinations": {
      "paramUrl": "inputs/Destinations"
    },
    "Travel_Mode": {
      "paramUrl": "inputs/Travel_Mode"
    },
    "Time_Units": {
      "paramUrl": "inputs/Time_Units"
    },
    "Distance_Units": {
      "paramUrl": "inputs/Distance_Units"
    },
    "Analysis_Region": {
      "paramUrl": "inputs/Analysis_Region"
    },
    "Number_of_Destinations_to_Find": {
      "paramUrl": "inputs/Number_of_Destinations_to_Find"
    },
    "Cutoff": {
      "paramUrl": "inputs/Cutoff"
    },
    "Time_of_Day": {
      "paramUrl": "inputs/Time_of_Day"
    },
    "Time_Zone_for_Time_of_Day": {
      "paramUrl": "inputs/Time_Zone_for_Time_of_Day"
    },
    "Point_Barriers": {
      "paramUrl": "inputs/Point_Barriers"
    },
    "Line_Barriers": {
      "paramUrl": "inputs/Line_Barriers"
    },
    "Polygon_Barriers": {
      "paramUrl": "inputs/Polygon_Barriers"
    },
    "UTurn_at_Junctions": {
      "paramUrl": "inputs/UTurn_at_Junctions"
    },
    "Use_Hierarchy": {
      "paramUrl": "inputs/Use_Hierarchy"
    },
    "Restrictions": {
      "paramUrl": "inputs/Restrictions"
    },
    "Attribute_Parameter_Values": {
      "paramUrl": "inputs/Attribute_Parameter_Values"
    },
    "Impedance": {
      "paramUrl": "inputs/Impedance"
    },
    "Origin_Destination_Line_Shape": {
      "paramUrl": "inputs/Origin_Destination_Line_Shape"
    }
  },
  "messages": []
}

Request to return origin-destination lines

https://<gpservice-url>/GenerateOriginDestinationCostMatrix/jobs/<jobID>/results/output_origin_destination_lines?f=pjson&token=<yourToken>

https://<gpservice-url>/GenerateOriginDestinationCostMatrix/jobs/<jobID>/results/output_origin_destination_lines?f=pjson&token=<yourToken>

JSON Response

{
  "paramName": "Output_Origin_Destination_Lines",
  "dataType": "GPFeatureRecordSetLayer",
  "value": {
    "displayFieldName": "",
    "geometryType": "esriGeometryPolyline",
    "spatialReference": {
      "wkid": 4326,
      "latestWkid": 4326
    },
    "fields": [
      {
        "name": "OBJECTID",
        "type": "esriFieldTypeOID",
        "alias": "OBJECTID"
      },
      {
        "name": "DestinationRank",
        "type": "esriFieldTypeInteger",
        "alias": "Destination Rank"
      },
      {
        "name": "Total_Time",
        "type": "esriFieldTypeDouble",
        "alias": "Total Time (Minutes)"
      },
      { 
        "name": "Total_Distance",
        "type": "esriFieldTypeDouble",
        "alias": "Total Distance (Kilometers)"
      },
      {
        "name": "OriginName",
        "type": "esriFieldTypeString",
        "alias": "Origin Name",
        "length": 128
      },
      {
        "name": "OriginOID",
        "type": "esriFieldTypeInteger",
        "alias": "Origin OID"
      },
      {
        "name": "DestinationName",
        "type": "esriFieldTypeString",
        "alias": "Destination Name",
        "length": 128
      },
      {
        "name": "DestinationOID",
        "type": "esriFieldTypeInteger",
        "alias": "Destination OID"
      },
      {
        "name": "Shape_Length",
        "type": "esriFieldTypeDouble",
        "alias": "Shape_Length"
      }
    ],
    "features": [
      {
        "attributes": {
          "OBJECTID": 1,
          "DestinationRank": 1,
          "Total_Time": 6.2279130881726257,
          "Total_Distance": 2.4774838708418678,
          "OriginName": "Origin 1",
          "OriginOID": 1,
          "DestinationName": "Destination 1",
          "DestinationOID": 1,
          "Shape_Length": 0
        }
      },
      {
        "attributes": {
          "OBJECTID": 2,
          "DestinationRank": 2,
          "Total_Time": 9.0778785641163715,
          "Total_Distance": 3.723118842219868,
          "OriginName": "Origin 1",
          "OriginOID": 1,
          "DestinationName": "Destination 2",
          "DestinationOID": 2,
          "Shape_Length": 0
        }
      },
      {
        "attributes": {
          "OBJECTID": 3,
          "DestinationRank": 1,
          "Total_Time": 4.6095379183132064,
          "Total_Distance": 1.9294457981067437,
          "OriginName": "Origin 2",
          "OriginOID": 2,
          "DestinationName": "Destination 2",
          "DestinationOID": 2,
          "Shape_Length": 0
        }
      },
      {
        "attributes": {
          "OBJECTID": 4,
          "DestinationRank": 2,
          "Total_Time": 6.0035312672863181,
          "Total_Distance": 2.3148191217414382,
          "OriginName": "Origin 2",
          "OriginOID": 2,
          "DestinationName": "Destination 1",
          "DestinationOID": 1,
          "Shape_Length": 0
        }
      }
    ],
    "exceededTransferLimit": false
  }
}

Request to return output origins

https://<gpservice-url>/GenerateOriginDestinationCostMatrix/jobs/<jobID>/results/output_origins?f=pjson&token=<yourToken>

https://<gpservice-url>/GenerateOriginDestinationCostMatrix/jobs/<jobID>/results/output_origins?f=pjson&token=<yourToken>

JSON Response

{
  "paramName": "Output_Origins",
  "dataType": "GPFeatureRecordSetLayer",
  "value": {
    "displayFieldName": "",
    "geometryType": "esriGeometryPoint",
    "spatialReference": {
      "wkid": 4326,
      "latestWkid": 4326
    },
    "fields": [
      {
        "name": "OBJECTID",
        "type": "esriFieldTypeOID",
        "alias": "OBJECTID"
      },
      {
        "name": "Name",
        "type": "esriFieldTypeString",
        "alias": "Name",
        "length": 128
      },
      {
        "name": "TargetDestinationCount",
        "type": "esriFieldTypeInteger",
        "alias": "Target Destination Count"
      },
      {
        "name": "CurbApproach",
        "type": "esriFieldTypeInteger",
        "alias": "Curb Approach"
      },
      {
        "name": "Status",
        "type": "esriFieldTypeInteger",
        "alias": "Status"
      },
      {
        "name": "Cutoff",
        "type": "esriFieldTypeDouble",
        "alias": "Cutoff"
      },
      {
        "name": "OriginOID",
        "type": "esriFieldTypeInteger",
        "alias": "Origin OID"
      },
      {
        "name": "DestinationCount",
        "type": "esriFieldTypeInteger",
        "alias": "Destination Count"
      }
    ],
    "features": [
      {
        "attributes": {
          "OBJECTID": 1,
          "Name": "Origin 1",
          "TargetDestinationCount": 2,
          "CurbApproach": 0,
          "Status": 0,
          "Cutoff": 120,
          "OriginOID": 1,
          "DestinationCount": 2
        },
        "geometry": {
          "x": -0.18909999999993943,
          "y": 51.525400000000047
        }
      },
      {
        "attributes": {
          "OBJECTID": 2,
          "Name": "Origin 2",
          "TargetDestinationCount": 2,
          "CurbApproach": 0,
          "Status": 0,
          "Cutoff": 90,
          "OriginOID": 2,
          "DestinationCount": 2
        },
        "geometry": {
          "x": -0.17439999999993461,
          "y": 51.535300000000063
        }
      }
    ],
    "exceededTransferLimit": false
  }
}

Request to return output destinations

https://<gpservice-url>/GenerateOriginDestinationCostMatrix/jobs/<jobID>/results/output_destinations?f=pjson&token=<yourToken>

https://<gpservice-url>/GenerateOriginDestinationCostMatrix/jobs/<jobID>/results/output_destinations?f=pjson&token=<yourToken>

JSON Response

{
  "paramName": "Output_Destinations",
  "dataType": "GPFeatureRecordSetLayer",
  "value": {
    "displayFieldName": "",
    "geometryType": "esriGeometryPoint",
    "spatialReference": {
      "wkid": 4326,
      "latestWkid": 4326
    },
    "fields": [
      {
        "name": "OBJECTID",
        "type": "esriFieldTypeOID",
        "alias": "OBJECTID"
      },
      {
        "name": "Name",
        "type": "esriFieldTypeString",
        "alias": "Name",
        "length": 128
      },
      {
        "name": "CurbApproach",
        "type": "esriFieldTypeInteger",
        "alias": "Curb Approach"
      },
      {
        "name": "Status",
        "type": "esriFieldTypeInteger",
        "alias": "Status"
      },
      {
        "name": "DestinationOID",
        "type": "esriFieldTypeInteger",
        "alias": "Destination OID"
      },
      {
        "name": "OriginCount",
        "type": "esriFieldTypeInteger",
        "alias": "Origin Count"
      }
    ],
    "features": [
      {
        "attributes": {
          "OBJECTID": 1,
          "Name": "Destination 1",
          "CurbApproach": 0,
          "Status": 0,
          "DestinationOID": 1,
          "OriginCount": 2
        },
        "geometry": {
          "x": -0.19909999999993033,
          "y": 51.535400000000038
        }
      },
      {
        "attributes": {
          "OBJECTID": 2,
          "Name": "Destination 2",
          "CurbApproach": 0,
          "Status": 0,
          "DestinationOID": 2,
          "OriginCount": 2
        },
        "geometry": {
          "x": -0.18439999999992551,
          "y": 51.545800000000042
        }
      }
    ],
    "exceededTransferLimit": false
  }
}