Points of Interest API
Points-of-Interest (POI) is implemented as a REST API endpoint. The POI endpoint receives an HTTP post to this URL:
http://{WebSERVER path to POI endpoint}/api/v1/loads/poi
A load number is passed in the body of the request to make the response relative to a specific load for dispatch, pickup, or an associated less-than-load (LTL) order.
{
"loadNumber": "1234567"
}
The API returns the POI items in Geo JSON format (to learn more, see http://geojson.org/geojson-spec.html). The response is a collection of Geo JSON features that contain an ID and the POI coordinates.
Note: The ID should be "FuelStop" and is needed for the app to show the POI.
The following POI properties are incorporated into this API for each point-of-interest (POI) and appear in the mobile app:
-
Name
-
CompanyID
-
Address
-
CustomNotes
Get POI Specification
URI
/api/v1/loads/poi
Headers
Authorization: {default token}
Methods
POST — Submit new POI request
Params
POI request JSON as below:
{
"loadNumber": "123456"
}
Response Http status 200
Successful response returns valid Geo JSON as shown below near the end of this article.
{
…
}
Error Codes
500 — Internal Server Error
{
"error": "Database error retrieving points"
}
The properties area of a point of interest contains custom attributes, depending on which point of interest we intend to present to the driver. These are some of the properties we have used in previous implementations:
For weather hazard POI:
-
name
-
color
-
date
-
ice
-
snow
-
wind
For trailers:
-
company
-
trailerId
-
assignedTo
POI Implementation Example
A few code snippets of a POI implementation using ASP.NET Web API 2 are included below. The project uses the GeoJSON.NET Nuget package (see https://github.com/GeoJSON-Net/GeoJSON.Net).
The following concepts are defined in the GeoJSON.NET library:
-
feature
-
geographic position
-
point
This is the Web API controller method that defines the endpoint:
public HttpResponseMessage Post([FromBody] PointsOfInterestQuery poiQuery)
{
try
{
IEnumerable<PointOfInterest> result;
result = Integration.RunPointsOfInterestQuery(poiQuery);
var features = result == null ? new List<Feature>() : result.Select(i => ConvertToGeoJSONFeature(i)).ToList();
var featuresCollection = new FeatureCollection();
featuresCollection.Features.AddRange(features);
return Request.CreateResponse(HttpStatusCode.OK, featuresCollection);
}
catch (Exception ex)
{
Log.Error(ex);
return Request.CreateResponse(HttpStatusCode.InternalServerError,
new ErrorModel { Error = "Error: " + ex.Message });
}
}
private Feature ConvertToGeoJSONFeature(PointOfInterest poi)
{
GeographicPosition position = new GeographicPosition(poi.latitude.To<double>(), poi.longitude.To<double>(), 0);
Point point = new Point(position);
Dictionary<string, object> properties = new Dictionary<string, object>();
if (!Text.IsBlank(poi.name))
properties.Add("name", poi.name);
if (!Text.IsBlank(poi.date))
properties.Add("date", poi.date);
if (!Text.IsBlank(poi.ice))
properties.Add("ice", poi.ice);
if (!Text.IsBlank(poi.snow))
properties.Add("snow", poi.snow);
if (!Text.IsBlank(poi.wind))
properties.Add("wind", poi.wind);
if (poi.Properties != null && poi.Properties.Count > 0)
{
foreach(var property in poi.Properties)
{
if (!Text.IsBlank(property.Name) && !Text.IsBlank(property.Value))
properties.Add(property.Name, property.Value);
}
}
Feature feature = new Feature(point, properties);
feature.Id = poi.featureId;
return feature;
}
Successful Response Geo JSON Example
{
"features": [{
"geometry": {
"coordinates": [
90.762,
41.509,
0
],
"type": "Point"
},
"id": "FuelStop",
"properties": {
"name": "FP964 - QUEST LINER, IN",
"companyId": "FP964 - QUEST LINER, IN",
"address": "550 W Mayne St., 563-451-1034 ",
"customNotes": "BLUE GRASS, IA"
},
"type": "Feature"
}, {
"geometry": {
"coordinates": [
91.67398,
41.8918,
0
],
"type": "Point"
},
"id": "FuelStop",
"properties": {
"name": "IA701 - KWIK STAR",
"companyId": "IA701 - KWIK STAR",
"address": "I-380, EXIT 13,319-362-3096 ",
"customNotes": "CEDAR RAPIDS, IA"
},
"type": "Feature"
}, {
"geometry": {
"coordinates": [
90.66643,
42.04949,
0
],
"type": "Point"
},
"id": "FuelStop",
"properties": {
"name": "IA899 - KWIK STAR 212",
"companyId": "IA899 - KWIK STAR 212",
"address": "102 DAVID ST EXIT 156, 563-652-4934 ",
"customNotes": "MAQUOKETA, IA"
},
"type": "Feature"
}, {
"geometry": {
"coordinates": [
90.62486,
41.60282,
0
],
"type": "Point"
},
"id": "FuelStop",
"properties": {
"name": "FJ636 - Flying J",
"companyId": "FJ636 - Flying J",
"address": "8200 N.W. Blvd., I-80 Exit 292,3193867710 ",
"customNotes": "Davenport, IA 52806"
},
"type": "Feature"
}, {
"geometry": {
"coordinates": [
90.62486,
41.60282,
0
],
"type": "Point"
},
"id": "FuelStop",
"properties": {
"name": "PK636 - Pilot Travel Center Kiosk",
"companyId": "PK636 - Pilot Travel Center Kiosk",
"address": "8200 N.W. Blvd, I-80 Exit 292, ",
"customNotes": "Davenport, IA 52806"
},
"type": "Feature"
}, {
"geometry": {
"coordinates": [
93.62513,
37.90935,
0
],
"type": "Point"
},
"id": "FuelStop",
"properties": {
"name": "PT385 - Pilot Travelcenters",
"companyId": "PT385 - Pilot Travelcenters",
"address": "Hwy 13 South and US 54, Hwy 13 / US 54, ",
"customNotes": "Collins, MO 64738"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
