Locate

The Locate service provides detailed information about streets and intersections close to an input point with some added matching criteria. This allows for tight integration in routing and navigation applications on web or mobile.

SecurityApiKeyAuth
Request
Request Body schema: application/json
Array of objects >= 2 items
costing
string (CostingModel)

Routing service uses dynamic, run-time costing to generate the route path. The route request must include the name of the costing model and can include optional parameters available for the chosen costing model.

  • auto - Standard costing for driving routes by car, motorcycle, truck, and so on that obeys automobile driving rules, such as access and turn restrictions. Auto provides a short time path (though not guaranteed to be shortest time) and uses intersection costing to minimize turns and maneuvers or road name changes. Routes also tend to favor highways and higher classification roads, such as motorways and trunks.
  • bicycle - Standard costing for travel by bicycle, with a slight preference for using cycleways or roads with bicycle lanes. Bicycle routes follow regular roads when needed, but avoid roads without bicycle access.
  • bus - Standard costing for bus routes. Bus costing inherits the auto costing behaviors, but checks for bus access on the roads.
  • bikeshare - A combination of pedestrian and bicycle. Use bike share station(amenity:bicycle_rental) to change the travel mode.
  • truck - Standard costing for trucks. Truck costing inherits the auto costing behaviors, but checks for truck access, width and height restrictions, and weight limits on the roads.
  • taxi - Standard costing for taxi routes. Taxi costing inherits the auto costing behaviors, but checks for taxi lane access on the roads and favors those roads.
  • motor_scooter - Standard costing for travel by motor scooter or moped. By default, motor_scooter costing will avoid higher class roads unless the country overrides allows motor scooters on these roads. Motor scooter routes follow regular roads when needed, but avoid roads without motor_scooter, moped, or mofa access.
  • motorcycle - Standard costing for travel by motorcycle. This costing model provides options to tune the route to take roadways (road touring) vs. tracks and trails (adventure motorcycling).
  • pedestrian - Standard walking route that excludes roads without pedestrian access. In general, pedestrian routes are shortest distance with the following exceptions: walkways and footpaths are slightly favored, while steps or stairs and alleys are slightly avoided.
  • multimodal - pedestrian and transit
Enum: "auto" "bicycle" "bus" "bikeshare" "truck" "taxi" "motor_scooter" "motorcycle" "pedestrian" "multimodal"
object

Costing methods can have several options that can be adjusted to develop the route path, as well as for estimating time along the path. Specify costing model options in your request using the format of costing_options.type, such as auto.

  • Cost options are fixed costs in seconds that are added to both the path cost and the estimated time. Examples of costs are gate_costs and toll_booth_costs, where a fixed amount of time is added. Costs are not generally used to influence the route path; instead, use penalties to do this. Costs must be in the range of 0.0 seconds to 43200.0 seconds (12 hours), otherwise a default value will be assigned.
  • Penalty options are fixed costs in seconds that are only added to the path cost. Penalties can influence the route path determination but do not add to the estimated time along the path. For example, add a toll_booth_penalty to create route paths that tend to avoid toll booths. Penalties must be in the range of 0.0 seconds to 43200.0 seconds (12 hours), otherwise a default value will be assigned.
  • Factor options are used to multiply the cost along an edge or road section in a way that influences the path to favor or avoid a particular attribute. Factor options do not impact estimated time along the path, though. Factors must be in the range 0.1 to 100000.0, where factors of 1.0 have no influence on cost. Anything outside of this range will be assigned a default value. Use a factor less than 1.0 to attempt to favor paths containing preferred attributes, and a value greater than 1.0 to avoid paths with undesirable attributes. Avoidance factors are more effective than favor factors at influencing a path. A factor's impact also depends on the length of road containing the specified attribute, as longer roads have more impact on the costing than very short roads. For this reason, penalty options tend to be better at influencing paths. A special costing option is shortest, which, when true, will solely use distance as cost and disregard all other costs, penalties and factors. It's available for all costing models except multimodal & bikeshare. Another special case is disable_hierarchy_pruning costing option. As the name indicates, disable_hierarchy_pruning = true will disable hierarchies in routing algorithms, which allows us to find the actual optimal route even in edge cases. For example, together with shortest = true they can find the actual shortest route. When disable_hierarchy_pruning is true and arc distances between source and target are not above the max limit, the actual optimal route will be calculated at the expense of performance. Note that if arc distances between locations exceed the max limit, disable_hierarchy_pruning is true will not be applied. This costing option is available for all motorized costing models, i.e auto, motorcycle, motor_scooter, bus, truck & taxi. For bicycle and pedestrian hierarchies are always disabled by default.
verbose
boolean

Can be set to true or false, but defaults to false. If set to true dense attribution of the given street or intersection will be returned.

object
Responses
200

Locate result.

400

Incorrect request parameters.

401

API key is incorrect or not provided.

402

Subscription daily limit exceeded.

403

Subscription suspended.

post/route/locate
Request samples
application/json
{
  • "locations": [
    • {
      • "lat": -90,
      • "lon": -180
      },
    • {
      • "lat": -90,
      • "lon": -180
      }
    ],
  • "costing": "auto",
  • "costing_options": {
    • "auto": {
      • "maneuver_penalty": 5,
      • "gate_cost": 30,
      • "gate_penalty": 300,
      • "private_access_penalty": 450,
      • "toll_booth_cost": 15,
      • "toll_booth_penalty": 0,
      • "ferry_cost": 300,
      • "use_ferry": 0.5,
      • "use_highways": 1,
      • "use_tolls": 0.5,
      • "use_living_streets": 1,
      • "use_tracks": 1,
      • "service_penalty": 0,
      • "service_factor": 1,
      • "country_crossing_cost": 600,
      • "country_crossing_penalty": 1,
      • "shortest": false,
      • "disable_hierarchy_pruning": false,
      • "top_speed": 140,
      • "fixed_speed": 0,
      • "ignore_closures": true,
      • "closure_factor": 9,
      • "height": 0,
      • "width": 0,
      • "exclude_unpaved": true,
      • "exclude_cash_only_tolls": false,
      • "include_hov2": false,
      • "include_hov3": false,
      • "include_hot": false
      },
    • "bus": {
      • "maneuver_penalty": 5,
      • "gate_cost": 30,
      • "gate_penalty": 300,
      • "private_access_penalty": 450,
      • "toll_booth_cost": 15,
      • "toll_booth_penalty": 0,
      • "ferry_cost": 300,
      • "use_ferry": 0.5,
      • "use_highways": 1,
      • "use_tolls": 0.5,
      • "use_living_streets": 1,
      • "use_tracks": 1,
      • "service_penalty": 0,
      • "service_factor": 1,
      • "country_crossing_cost": 600,
      • "country_crossing_penalty": 1,
      • "shortest": false,
      • "disable_hierarchy_pruning": false,
      • "top_speed": 140,
      • "fixed_speed": 0,
      • "ignore_closures": true,
      • "closure_factor": 9,
      • "height": 0,
      • "width": 0,
      • "exclude_unpaved": true,
      • "exclude_cash_only_tolls": false,
      • "include_hov2": false,
      • "include_hov3": false,
      • "include_hot": false
      },
    • "truck": {
      • "maneuver_penalty": 5,
      • "gate_cost": 30,
      • "gate_penalty": 300,
      • "private_access_penalty": 450,
      • "toll_booth_cost": 15,
      • "toll_booth_penalty": 0,
      • "ferry_cost": 300,
      • "use_ferry": 0.5,
      • "use_highways": 1,
      • "use_tolls": 0.5,
      • "use_living_streets": 1,
      • "use_tracks": 1,
      • "service_penalty": 0,
      • "service_factor": 1,
      • "country_crossing_cost": 600,
      • "country_crossing_penalty": 1,
      • "shortest": false,
      • "disable_hierarchy_pruning": false,
      • "top_speed": 140,
      • "fixed_speed": 0,
      • "ignore_closures": true,
      • "closure_factor": 9,
      • "height": 0,
      • "width": 0,
      • "exclude_unpaved": true,
      • "exclude_cash_only_tolls": false,
      • "include_hov2": false,
      • "include_hov3": false,
      • "include_hot": false,
      • "length": 21.64,
      • "weight": 21.77,
      • "axle_load": 9.07,
      • "axle_count": 5,
      • "hazmat": false
      },
    • "taxi": {
      • "height": 0,
      • "width": 0,
      • "exclude_unpaved": true,
      • "exclude_cash_only_tolls": false,
      • "include_hov2": false,
      • "include_hov3": false,
      • "include_hot": false
      },
    • "bicycle": {
      • "bicycle_type": "Road",
      • "cycling_speed": 18,
      • "use_roads": 0.5,
      • "use_hills": 0.5,
      • "use_ferry": 0.5,
      • "use_living_streets": 0.5,
      • "avoid_bad_surfaces": 0.25,
      • "bss_return_cost": 120,
      • "shortest": false
      },
    • "bikeshare": {
      • "walking_speed": 5.1,
      • "walkway_factor": 1,
      • "sidewalk_factor": 1,
      • "alley_factor": 2,
      • "driveway_factor": 5,
      • "step_penalty": 0,
      • "use_ferry": 0.5,
      • "use_living_streets": 0.5,
      • "use_tracks": 0.5,
      • "use_hills": 0.5,
      • "use_lit": 0,
      • "service_penalty": 0,
      • "service_factor": 1,
      • "max_hiking_difficulty": 1,
      • "bss_rent_cost": 120,
      • "shortest": false,
      • "transit_start_end_max_distance": 2145,
      • "transit_transfer_max_distance": 800,
      • "bicycle_type": "Road",
      • "cycling_speed": 18,
      • "use_roads": 0.5,
      • "avoid_bad_surfaces": 0.25,
      • "bss_return_cost": 120
      },
    • "motor_scooter": {
      • "top_speed": 45,
      • "use_primary": 0.5,
      • "use_hills": 0.5,
      • "shortest": false,
      • "disable_hierarchy_pruning": false
      },
    • "motorcycle": {
      • "use_highways": 1,
      • "use_trails": 0,
      • "shortest": false,
      • "disable_hierarchy_pruning": false
      },
    • "pedestrian": {
      • "walking_speed": 5.1,
      • "walkway_factor": 1,
      • "sidewalk_factor": 1,
      • "alley_factor": 2,
      • "driveway_factor": 5,
      • "step_penalty": 0,
      • "use_ferry": 0.5,
      • "use_living_streets": 0.6,
      • "use_tracks": 0.5,
      • "use_hills": 0.5,
      • "use_lit": 0,
      • "service_penalty": 0,
      • "service_factor": 1,
      • "max_hiking_difficulty": 1,
      • "bss_rent_cost": 120,
      • "shortest": false,
      • "transit_start_end_max_distance": 2145,
      • "transit_transfer_max_distance": 800
      },
    • "transit": {
      • "use_bus": 1,
      • "use_rail": 1,
      • "use_transfers": 1,
      • "filters": {
        • "routes": {
          • "ids": [
            • "NYC_AUR"
            ],
          • "action": "exclude"
          },
        • "operators": {
          • "ids": [
            • "paris_CFG"
            ],
          • "action": "exclude"
          }
        }
      },
    • "multimodal": {
      • "use_bus": 1,
      • "use_rail": 1,
      • "use_transfers": 1,
      • "filters": {
        • "routes": {
          • "ids": [
            • "NYC_AUR"
            ],
          • "action": "exclude"
          },
        • "operators": {
          • "ids": [
            • "paris_CFG"
            ],
          • "action": "exclude"
          }
        }
      }
    },
  • "verbose": true,
  • "directions_options": {
    • "units": "km"
    }
}
Response samples
application/json
[
  • {
    • "reason": "string",
    • "input_lat": 0,
    • "input_lon": 0,
    • "nodes": [
      • {
        • "lat": 0,
        • "lon": 0
        }
      ],
    • "edges": [
      • {
        • "side_of_street": "string",
        • "correlated_lat": 0,
        • "correlated_lon": 0,
        • "percent_along": 0,
        • "way_id": 0
        }
      ]
    }
]
Copyright © Pickpointio LLC 2023. All rights reserved.