RESTful APIs

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 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
Last updated June 7, 2024.
API Endpoint:
AWS Azure
Contents