POIs Along the Route

Contents

The POIs Along the Route request retrieves the Points of Interest (POIs) along a given route. Requires add-on license

POST /poi/alongRoute?dataset={dataset}

Resource URL

https://pcmiler.alk.com/apis/rest/v1.0/service.svc/poi/alongRoute?dataset={dataset}

Path Parameter

Parameter	Definition	Data Type	Required
`dataset`	For users licensed for multiple datasets. Read more about setting the `dataset`.	string	N

Report Request Parameters

POIs along the route requests require Stops on the route, a RouteLegIndex, and a SearchType. The additional parameters below can help you narrow your search.

Route Options and Extended Options can be set to customize the route.

POI Along the Route Parameters

Data Element	Description	Data Type	Value/Example
`RouteLegIndex`	The leg of the route where you want to search for POIs.	int	0
`SearchType`	The type of POI search. 1 - FuelStop 2 - HoS 4 - Generic	enum	2
`HoSPOICategories`	The categories that can be used to narrow an `Hos` type search. 0 - All 1600 - TruckServiceHoS 1510 - RestAreaHoS	enum	2
`SearchWindowUnits`	The type of search window along the route. 0 - Miles 1 - Minutes	enum	1
`SearchWindowStart`	The miles/minutes (based on `SearchWindowUnits`) on the route leg at which to begin the search. Set to `0` or `null` to search at the beginning of the leg	double	30
`SearchWindowEnd`	The miles/minutes (based on `SearchWindowUnits`) on the route leg at which to end the search. Set to `null` to automatically select the end of the leg or the maximum allowed length—100 miles or minutes—whichever is smaller.	double	120
`AirDistanceThreshold`	The maximum air distance between the POI and the nearest intersection on the route. Default and maximum is 2.5 miles.	double	1.5

ExtendedOptions

Data Element Description Data Type Value/Example

EstimatedTimeOptions

Data Element	Description	Data Type	Value/Example
EstimatedTimeOptions	Estimated time options allow you to select when you would like to depart from your origin or arrive at your destination. You must select one of three options for your arrival or departure: The current time and day; a day of the week and time of day; or a specific date and time of day. This time will be reflected in mileage and detailed reports and can also affect routing with roads that have time-based restrictions. `EstimatedTimeOptions` is an object with the following values: `ETAETD` - Set to 0 for Arrival, 1 for Departure `DateOption` - Set to 0 for Current time, 1 for Specific time, 2 for DayOfWeek. `DateAndTime` - An object with the following values: `CalendarDate` - A string value for the month, day and year in the following format `mm/dd/yyyy.` `DateOption` must be set to 1 for this value to be used. `DayOfWeek` - Day of the week, starting at 0-Sunday, 1-Monday, 2-Tuesday and so on. `DateOption` must be set to 2 for this value to be used. `TimeOfDay` - A string value for the time in the format `hh:mm AM/PM`. `TimeZone` - Set to 0 for local time. Other supported time zones can be found here. When setting a departure time, if the request is sent in the same time zone as the first stop (origin of the trip), within 15 minutes of the current time, the current time will be returned in the response.	object	Example: `"EstimatedTimeOptions": { "ETAETD": 1, "DateOption": 1, "DateAndTime": { "CalendarDate": "11/21/2021", "DayOfWeek": 0, "TimeOfDay": "6:00 AM", "TimeZone": 0 } }`
UseTraffic	Indicates whether or not to use traffic data. When set to true, the routing algorithm will consider traffic closures when selecting the route and use historical traffic patterns to calculate the trip’s ETA and travel time. If set to true, and the trip’s departure time is also set to within 15 minutes of the current time, real-time traffic data will be used for the first 15 miles and historical traffic patterns will be used for the remainder of the route. (By default, `UseTraffic` is false, and ETA and travel time are computed using Trimble Maps’s average road speeds by road class.) With the exception of road closures, traffic data is only used to select the route path a vehicle will take when the routing algorithm (`RoutingType`) is set to `Fastest`. (Fastest routing is not recommended for trucks—autos and vans only.)	boolean	True False (Default)

Estimated time options allow you to select when you would like to depart from your origin or arrive at your destination. You must select one of three options for your arrival or departure: The current time and day; a day of the week and time of day; or a specific date and time of day. This time will be reflected in mileage and detailed reports and can also affect routing with roads that have time-based restrictions. EstimatedTimeOptions is an object with the following values:

ETAETD - Set to 0 for Arrival, 1 for Departure

DateOption - Set to 0 for Current time, 1 for Specific time, 2 for DayOfWeek.

DateAndTime - An object with the following values:

CalendarDate - A string value for the month, day and year in the following format mm/dd/yyyy. DateOption must be set to 1 for this value to be used.

DayOfWeek - Day of the week, starting at 0-Sunday, 1-Monday, 2-Tuesday and so on. DateOption must be set to 2 for this value to be used.

TimeOfDay - A string value for the time in the format hh:mm AM/PM.

TimeZone - Set to 0 for local time. Other supported time zones can be found here. When setting a departure time, if the request is sent in the same time zone as the first stop (origin of the trip), within 15 minutes of the current time, the current time will be returned in the response.

object

Example:


"EstimatedTimeOptions": {

   "ETAETD": 1,

   "DateOption": 1,

   "DateAndTime": {

     "CalendarDate": "11/21/2021",

     "DayOfWeek": 0,

     "TimeOfDay": "6:00 AM",

     "TimeZone": 0

   }

}

UseTraffic

Indicates whether or not to use traffic data. When set to true, the routing algorithm will consider traffic closures when selecting the route and use historical traffic patterns to calculate the trip’s ETA and travel time. If set to true, and the trip’s departure time is also set to within 15 minutes of the current time, real-time traffic data will be used for the first 15 miles and historical traffic patterns will be used for the remainder of the route. (By default, UseTraffic is false, and ETA and travel time are computed using Trimble Maps’s average road speeds by road class.)

With the exception of road closures, traffic data is only used to select the route path a vehicle will take when the routing algorithm (RoutingType) is set to Fastest. (Fastest routing is not recommended for trucks—autos and vans only.)

boolean

True
False (Default)

Sample JSON Post Body

Example for getting POIs along the route using a HoS search type.

{
    "PoiRoute": {
      "ExtendedOptions": null,
      "RouteId": "MiamiToPrinceton",
      "Stops": [
        {
          "Costs": null,
          "IsViaPoint": false,
          "Address": {
            "StreetAddress": null,
            "City": "Miami",
            "State": "FL",
            "Zip": null,
            "County": null,
            "Country": null,
            "SPLC": null,
            "CountryPostalFilter": 0,
            "AbbreviationFormat": 0
          },
          "Coords": null,
          "Region": 4,
          "Label": null,
          "PlaceName": null
        },
        {
          "Costs": null,
          "IsViaPoint": false,
          "Address": {
            "StreetAddress": null,
            "City": null,
            "State": null,
            "Zip": "08540",
            "County": null,
            "Country": null,
            "SPLC": null,
            "CountryPostalFilter": 0,
            "AbbreviationFormat": 0
          },
          "Coords": null,
          "Region": 4,
          "Label": null,
          "PlaceName": null
        }
      ],
      "Options": {
        "HighwayOnly": false
      }
    },
    "RouteLegIndex": 0,
    "SearchType": 2,
    "HoSPOICategories": [0],
    "SearchWindowUnits": 1,
    "SearchWindowStart": 30,
    "SearchWindowEnd": 120,
    "AirDistanceThreshold": 1.5
}

Sample Response

{
  "POISearchMatches": [
    {
      "POILocation": {
        "Address": {
          "StreetAddress": "810 North Congress Avenue",
          "City": "Riviera Beach",
          "State": "FL",
          "Zip": "33404",
          "County": "",
          "Country": "United States",
          "SPLC": null,
          "CountryPostalFilter": 0,
          "AbbreviationFormat": 0,
          "StateName": "Florida",
          "StateAbbreviation": "FL",
          "CountryAbbreviation": "US"
        },
        "Coords": {
          "Lat": "26.771411",
          "Lon": "-80.087143"
        },
        "Region": 4,
        "Label": "@Riviera Truck Stop",
        "PlaceName": "@Riviera Truck Stop"
      },
      "DistanceFromOrigin": {
        "Value": 74.785,
        "DistanceUnits": 0
      },
      "POICategory": "Truck Services (HOS)",
      "TimeFromOrigin": "01:23:00",
      "DistanceOffRoute": {
        "Value": 2.535,
        "DistanceUnits": 0
      },
      "PoiID": 6028,
      "SetID": 12,
      "PersistentID": 701003,
      "ParkingStatus": null
    },
    {
      "POILocation": {
        "Address": {
          "StreetAddress": "3691 W. Blue Heron Blvd.",
          "City": "Riviera Beach",
          "State": "FL",
          "Zip": "33404",
          "County": "",
          "Country": "United States",
          "SPLC": null,
          "CountryPostalFilter": 0,
          "AbbreviationFormat": 0,
          "StateName": "Florida",
          "StateAbbreviation": "FL",
          "CountryAbbreviation": "US"
        },
        "Coords": {
          "Lat": "26.782595",
          "Lon": "-80.095487"
        },
        "Region": 4,
        "Label": "@Marathon",
        "PlaceName": "@Marathon"
      },
      "DistanceFromOrigin": {
        "Value": 73.449,
        "DistanceUnits": 0
      },
      "POICategory": "Truck Services (HOS)",
      "TimeFromOrigin": "01:20:00",
      "DistanceOffRoute": {
        "Value": 0.347,
        "DistanceUnits": 0
      },
      "PoiID": 4653,
      "SetID": 12,
      "PersistentID": 702753,
      "ParkingStatus": {
        "ProviderParkingStatus": null,
        "UserParkingStatus": [
          {
            "ParkingStatus": "SomeSpots",
            "LastUpdated": 15526795589570000
          }
        ]
      }
    },
    {
      "POILocation": {
        "Address": {
          "StreetAddress": "",
          "City": "Palm City",
          "State": "FL",
          "Zip": "34990",
          "County": "",
          "Country": "United States",
          "SPLC": null,
          "CountryPostalFilter": 0,
          "AbbreviationFormat": 0,
          "StateName": "Florida",
          "StateAbbreviation": "FL",
          "CountryAbbreviation": "US"
        },
        "Coords": {
          "Lat": "27.128257",
          "Lon": "-80.332947"
        },
        "Region": 4,
        "Label": "Martin County Rest Area, I-95 North",
        "PlaceName": "Martin County Rest Area, I-95 North"
      },
      "DistanceFromOrigin": {
        "Value": 103.581,
        "DistanceUnits": 0
      },
      "POICategory": "Rest Area (HOS)",
      "TimeFromOrigin": "01:52:00",
      "DistanceOffRoute": {
        "Value": 0.011,
        "DistanceUnits": 0
      },
      "PoiID": 6870,
      "SetID": 12,
      "PersistentID": 704243,
      "ParkingStatus": null
    }
  ],
  "SearchStartCoordinates": {
    "Lat": "26.131962",
    "Lon": "-80.169199"
  },
  "SearchEndCoordinates": {
    "Lat": "27.208202",
    "Lon": "-80.400326"
  }
}

Errors

Data Element	Description	Data Type	Value/Example
`Type`	Indicates whether the error is an exception or warning	Enum	Warning Exception
`Code`	Error code	Enum	Please refer to Appendix for complete list
`LegacyErrorCode`	The legacy error code with is an integer valued code that would have been returned in PC*MILER Web Services v25 and earlier.	Int
`Description`	The detailed error description.	string

WEB SDK & APIs

INTERACTIVE MAPS

SOAP APIs (Web Services)

RESTful APIs (Web Services)

MOBILE SDK & APIs

COPILOT NAVIGATION