Geospatial
The Geospatial API is a RESTful web service that enables Verizon Connect customers to integrate 3rd party back-office systems with REVEAL to create and delete Geofences within their account.
A Geofence is a virtual perimeter created around a real-world location that’s used to categorize activity. Geofences can represent any type of location that is meaningful. Within REVEAL, Geofences are shown throughout the site in various places and will be shown to the user by the common name with or without the actual location address.
Important concepts to understand prior to utilizing any of the available integration methods:
· Geospatial API is offered as a RESTful web service
· Standard REST verbs are applied: GET, POST, PUT, and DELETE
· Throughout this document, we will reference the unique identifier to be invoked for each of the main objects available to be created or deleted. The unique identifier for the Geospatial API is as follows and can be reviewed within the REVEAL Geofence profile:
o Geofence = PlaceID
To assign a Geofence to a particular group, please see the Customer Meta Data Group API.
Note: The returned response will be restricted
to the Reveal account's data plan. If the information being queried is outside
of the data plan, a "400 Bad Request error "response will be
returned.
For more details on your account's data plan
please reach out to Verizon Connect Customer Support
API Name |
Geospatial API |
Endpoint |
|
Operation |
GET, POST, PUT, DELETE |
The GET Geofence enables integration users to retrieve Geofence data by Category Name and/or Group ID. The Category and Group management reside within REVEAL and are provided as additional Parameter Headers when calling the GET Geofence method.
The GET Geofence by Category method provides integration users with the ability to retrieve a list of Geofences assigned to a particular category. Categories are managed in the Places tab of REVEAL. Category names must be presented exactly as they are saved within REVEAL.
Operation and Path |
GET
https://fim.api.eu.fleetmatics.com/geo/v1/geofences?categoryName=<CategoryName>
HTTP/1.1 |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Authorisation |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
{
"Count": 1,
"_links": {
"self": {
"href": "http://api.eu.fleetmatics.com/GSM/v1/geofences?categoryName=REST%20Test"
}
},
"_embedded": {
"places": [
{
"place": {
"GeoShapeType": "GeoRectangle",
"PlaceId": "JC123",
"GeoFenceName": "Jennifer",
"CategoryName": "REST Test",
"Address": {
"AddressLine1": "2510 E Ridgewood Dr",
"AddressLine2": "",
"Locality": "Seven Hills",
"AdministrativeArea": "OH",
"PostalCode": "44131",
"Country": "USA"
},
"IsShownOnMap": true,
"IsShownOnReport": true,
"Note": "JC Rest Stop",
"PhoneNumber": "216-522-2855",
"Latitude": 41.391756,
"Longitude": -81.670929
},
"_links": {
"self": {
"href":
"http://api.eu.fleetmatics.com/GSM/v1/geofences/JC123"
},
"spatialdata":
{
"href": "http://api.eu.fleetmatics.com/GSM/v1/geofences/rectangles/JC123/spatialdata"
}
}
}
]
}
The GET Geofence by Group ID method provides integration users with the ability to retrieve a list of Geofences assigned to a particular Group. Geofences can be assigned to a Group using the Customer Meta Data – Group API.
Operation and Path |
GET
https://fim.api.eu.fleetmatics.com/geo/v1/geofences?groupId=<groupID>
HTTP/1.1 |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Authorisation |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
{
"Count": 6,
"_links": {
"self": {
"href": "http://api.eu.fleetmatics.com/GSM/v1/geofences?groupId=22325"
}
},
"_embedded": {
"places": [
{
"place": {
"GeoShapeType": "GeoPolygon",
"PlaceId": "(null)",
"GeoFenceName": "office",
"CategoryName": "Home Office",
"Address": {
"AddressLine1": "31625 Bainbridge Rd",
"AddressLine2": "",
"Locality": "Solon",
"AdministrativeArea": "OH",
"PostalCode": "44139",
"Country": "USA"
},
"IsShownOnMap": false,
"IsShownOnReport": false,
"Note": "(null)",
"PhoneNumber": "(null)",
"Latitude": 41.397899,
"Longitude": -81.454621
},
"_links": {
"self": {
"href": "http://api.eu.fleetmatics.com/GSM/v1/geofences/(null)"
},
"spatialdata": {
"href": ""
}
}
},
Field |
JSON
Formatted Sample |
Field
Notes and Default Values |
Count |
{ "Count": 1, "_links": { "self": { "href":
"http://api.us.fleetmatics.com/GSM/v1/geofences?categoryName=REST%20Test" } }, |
The total
number of Geofence locations assigned to the provided Category Name and/or
Group ID. In the
example above, only 1 Geofence is assigned to the Category/Group ID. |
Place
Details |
"_embedded":
{ "places": [ { "place": { |
Each
Geofence that is assigned to the Category queried will be displayed as a
Place object with specific details. |
GeoShape Type |
"GeoShapeType":
"GeoRectangle", |
Geofences
are able to be saved as a GeoRectangle, GeoCircle, or Polygon. |
Place ID |
"PlaceId":
"JC123", |
Place ID
is a unique value within a REVEAL account that is used to identify a
Geofence. To use the Geospatial API
the Place ID is a mandatory field. The
Place ID can be NULL for a returned Geofence. |
GeoFence Name |
"GeoFenceName":
"Jennifer", |
The name
of the Geofence. |
Category
Name |
"CategoryName":
"REST Test", |
The name
of the Category. |
Address |
{ “Address”:{ “AddressLine1”:”” “AddressLine2”:”” “Locality”:”” “Administrative Area”:”” “Postal Code”:”” “Country”:”” }, |
Address
contains the global standards for address components: ·
Address Line 1 – location
specific identification such as a house number ·
Address Line 2 – additional
information to identify location such as an apartment number ·
Locality – city, town, etc. ·
Administrative Area – state,
province, etc. ·
Postal Code ·
Country |
Is Shown
On Map |
"IsShownOnMap":
true, |
Boolean
value to denote if the Geofence can be displayed on the Map. Default
is True. |
Is Shown
on Report |
"IsShownOnReport":
true, |
Boolean
value to denote if the Geofence can be displayed on Reports. Default
is True. |
Note |
"Note": "JC Rest Stop", |
A Note is
a free form text space for users to provide additional details about the
Geofence location. |
Phone
Number |
"PhoneNumber":
"216-522-2855", |
A Phone
Number can be associated with the saved Geofence. |
Latitude |
"Latitude": 41.391756, |
|
Longitude |
"Longitude": -81.670929 }, |
|
Geofence
Link |
"_links":
{ "self": { "href":
"http://api.us.fleetmatics.com/GSM/v1/geofences/JC123" }, |
|
Spatial
Data Link |
"spatialdata": {
"href":
"http://api.us.fleetmatics.com/GSM/v1/geofences/rectangles/JC123/spatialdata"
} } } ] } } |
This link
will easily allow for the GET Spatial Data method to be referenced if the
user requires additional details about the specific Geofence. |
GET Geofence by Place ID enables integration users to retrieve details regarding a specific Geofence.
Operation and Path |
GET
https://fim.api.eu.fleetmatics.com/geo/v1/geofences/<PlaceID> HTTP/1.1 |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Authorisation |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
{
"geofence": {
"GeoShapeType": "GeoRectangle",
"PlaceId": "369852",
"GeoFenceName": "Restaurant",
"CategoryName": "UnCategorized",
"Address": {},
"IsShownOnMap": true,
"IsShownOnReport": true,
"Latitude": 53.389422,
"Longitude": -2.925248
},
"_links": {
"self": {
"href": "http://api.eu.fleetmatics.com/GSM/v1/geofences/369852"
},
"spatialdata":
{
"href":
"http://api.eu.fleetmatics.com/GSM/v1/geofences/rectangles/369852/spatialdata"
}
}
}
Field |
JSON Formatted Sample |
Field Notes and Default Values |
GeoShape Type |
{ "geofence": { "GeoShapeType": "GeoRectangle", |
Circle, Rectangle, or Polygon |
Place ID |
"PlaceId": "369852", |
Place ID is a unique value within a REVEAL account
that is used to identify a Geofence.
To use the Geospatial API the Place ID is a mandatory field. The Place ID can be NULL for a returned
Geofence. |
Geofence Name |
"GeoFenceName":
"Restaurant", |
|
Integration users have the option to collect more specific spatial data for a specific Geofence using the GET Geofence Spatial Data methods. The Spatial Data API options are broken down into Circle and Rectangle methods to provide all the granular details for a Geofence. Most users will collect the spatial data link for a Geofence through the GET Geofence method by Category or Group ID and then perform a subsequent call if the details for a Geofence are needed.
Operation and Path |
GET
https://fim.api.eu.fleetmatics.com/geo/v1/geofences/circles/<PlaceID>/spatialdata
HTTP/1.1 |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Authorisation |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
{
"ShapeType":
"Circle",
"Latitude": 41.396927,
"Longitude": -81.455925,
"RadiusInKm":
0.27561
}
Field |
JSON
Formatted Sample |
Field
Notes and Default Values |
Shape
Type |
{ "ShapeType":
"Circle", |
Circle,
Rectangle, or Polygon |
Latitude |
"Latitude": 41.396927, |
|
Longitude |
"Longitude": -81.455925, |
|
Radius In
KM |
"RadiusInKm":
0.27561 } |
The
designated radius in kilometers used to create the circular Geofence referenced. |
Operation and Path |
GET
https://fim.api.eu.fleetmatics.com/geo/v1/geofences/rectangles/<PlaceID>/spatialdata
HTTP/1.1 |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Authorisation |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
{
"ShapeType": "Rectangle",
"Latitude": 53.389422,
"LengthInKm": 0.3130492799997731,
"Longitude": -2.925248,
"WidthInKm": -0.40642887541418127
}
Field |
JSON Formatted Sample |
Field Notes and Default Values |
Shape Type |
{ "ShapeType":
"Rectangle", |
Circle, Rectangle, or Polygon |
Latitude |
"Latitude": 53.389422, |
|
Length In KM |
"LengthInKm":
0.3130492799997731, |
The length of the rectangular Geofence in
kilometers. |
Longitude |
"Longitude": -81.455925, |
|
Width In KM |
"WidthInKm":
-0.40642887541418127 } |
The width of the
rectangular Geofence in kilometers. |
The POST Circle Geofence method is available to create circular Geofences within REVEAL.
Operation and Path |
POST https://fim.api.eu.fleetmatics/geo/v1/geofences/circles
HTTP/1.1 |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Content-Length |
This value will auto-calculate based on the Content provided for
the Geofence details. |
Authorisation |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
· If the user provides only the “Address,” the Geofence will be created within the REVEAL account referencing the address provided within the request.
· If the user provides only the coordinates, the Geofence will be created within the REVEAL account referencing the latitude and longitude coordinates provided within the request.
o If the coordinates are being used and the user does not provide either the latitude or longitude value, an ERROR will be returned.
· If the user provides both the address and coordinate values within the same request, the Geofence will be created using the coordinate values.
· All Geofences created within a REVEAL account using the POST Geospatial methods will be assigned to the ENTIRE FLEET group. To change the Geofence’s group assignment the Customer Meta Data Group API will need to be referenced.
· Geofences can be assigned to a Category when created using the POST methods, but the Category Name will need to already exist within the REVEAL account. When adding the Category Name to the request, the name must exactly match what was created within the REVEAL account. If it does not an ERROR will be returned.
The content data that must be provided when calling the Create Circle Geofence method includes:
{
"RadiusInKm": 2,
"PlaceId": "123459",
"GeoFenceName": "Garage 203",
"Address": {
"AddressLine1": "3613 West 120 Street",
"Locality": "Cleveland",
"AdministrativeArea": "Oh",
"PostalCode": "44111",
"Country": "USA"
},
"IsShownOnMap": true,
"IsShownOnReport": true
}
When creating an object in REVEAL, the response returned for the API call
invoked will return the created object’s details.
The POST Rectangle Geofence method is available to create rectangular Geofences within REVEAL.
Operation and Path |
POST
https://fim.api.eu.fleetmatics.com/geo/v1/geofences/rectangles HTTP/1.1 |
HOST |
fim.api.eu.fleetmatics.com
|
Accept |
application/json |
Content-Length |
This value will
auto-calculate based on the Content provided for the Geofence details. |
Authorisation |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon
Connect App ID ], Bearer
[Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
· If the user provides only the “Address,” the Geofence will be created within the REVEAL account referencing the address provided within the request.
· If the user provides only the coordinates, the Geofence will be created within the REVEAL account referencing the latitude and longitude coordinates provided within the request.
o If the coordinates are being used and the user does not provide either the latitude or longitude value, an ERROR will be returned.
· If the user provides both the address and coordinate values within the same request, the Geofence will be created using the coordinate values.
· All Geofences created within a REVEAL account using the POST Geospatial methods will be assigned to the ENTIRE FLEET group. To change the Geofence’s group assignment the Customer Meta Data Group API will need to be referenced.
· Geofences can be assigned to a Category when created using the POST methods, but the Category Name will need to already exist within the REVEAL account. When adding the Category Name to the request, the name must exactly match what was created within the REVEAL account. If it does not an ERROR will be returned.
The content data that must be provided when calling the Create Circle Geofence method includes:
{
"LengthInKm": 1,
"WidthInKm": 1,
"PlaceId": "996788",
"GeoFenceName": "Revtangle",
"CategoryName": "UnCategorized",
"Address": {
"AddressLine1": "4556 South Drive",
"Locality": "Seven Hills",
"AdministrativeArea": "Oh",
"PostalCode": "44131",
"Country": "USA"
},
"IsShownOnMap": true,
"IsShownOnReport": true
}
When creating an object in REVEAL, the
response returned for the API call invoked will return the created object’s
details.
PUT Methods
The PUT Circle Geofence method is available to edit existing circular Geofences within REVEAL.
Operation and Path |
PUT
https://fim.api.eu.fleetmatics.com/geo/v1/geofences/circles/<PlaceID>
HTTP/1.1 |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Content-Length |
This value will auto-calculate based on the Content provided for
the Geofence details. |
Authorisation |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
· If the user provides only the “Address,” the Geofence will be created within the REVEAL account referencing the address provided within the request.
· If the user provides only the coordinates, the Geofence will be created within the REVEAL account referencing the latitude and longitude coordinates provided within the request.
o If the coordinates are being used and the user does not provide either the latitude or longitude value, an ERROR will be returned.
· If the user provides both the address and coordinate values within the same request, the Geofence will be created using the coordinate values.
· All Geofences created within a REVEAL account using the POST Geospatial methods will be assigned to the ENTIRE FLEET group. To change the Geofence’s group assignment the Customer Meta Data Group API will need to be referenced.
· Geofences can be assigned to a Category when created using the POST methods, but the Category Name will need to already exist within the REVEAL account. When adding the Category Name to the request, the name must exactly match what was created within the REVEAL account. If it does not an ERROR will be returned.
PUT methods will not return an object review. The response will be limited to a set of standard HTTP codes:
· Successfully edited Geofences will return a 200 code
· Unfound Place IDs, or the unique identifier used for the call, will return a 404 error
· Bad requests, typically due to an error in the call’s content, will return a 400 error
· Invalid tokens or an Authorisation problem will return a 401 error
· If the service is unavailable at the time the call was made a 500 error will return
The PUT Rectangle Geofence method is available to edit existing rectangular Geofences within REVEAL.
Operation and Path |
PUT
https://fim.api.eu.fleetmatics.com/geo/v1/geofences/rectangles/ <PlaceID> HTTP/1.1 |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Content-Length |
This value will auto-calculate based on the Content provided for
the Geofence details. |
Authorisation |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
· If the user provides only the “Address,” the Geofence will be created within the REVEAL account referencing the address provided within the request.
· If the user provides only the coordinates, the Geofence will be created within the REVEAL account referencing the latitude and longitude coordinates provided within the request.
o If the coordinates are being used and the user does not provide either the latitude or longitude value, an ERROR will be returned.
· If the user provides both the address and coordinate values within the same request, the Geofence will be created using the coordinate values.
· All Geofences created within a REVEAL account using the POST Geospatial methods will be assigned to the ENTIRE FLEET group. To change the Geofence’s group assignment the Customer Meta Data Group API will need to be referenced.
· Geofences can be assigned to a Category when created using the POST methods, but the Category Name will need to already exist within the REVEAL account. When adding the Category Name to the request, the name must exactly match what was created within the REVEAL account. If it does not an ERROR will be returned.
PUT methods will not return an object review. The response will be limited to a set of standard HTTP codes:
· Successfully edited Geofences will return a 200 code
· Unfound Place IDs, or the unique identifier used for the call, will return a 404 error
· Bad requests, typically due to an error in the call’s content, will return a 400 error
· Invalid tokens or an Authorisation problem will return a 401 error
· If the service is unavailable at the time the call was made a 500 error will return
The DELETE Geofence method is available for deleting any Geofence shape type from a REVEAL account.
Operation and Path |
DELETE https://fim.api.eu.fleetmatics.com/geo/v1/geofences/<PlaceID>
HTTP/1.1 |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Authorisation |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
The DELETE Geofence method will not return an object review. The response will be limited to a set of standard HTTP codes:
· Successfully deleted Geofences will return a 200 code
· Unfound Place IDs, or the unique identifier used for the call, will return a 404 error
· Bad requests, typically due to an error in the call’s content, will return a 400 error
· Invalid tokens or an Authorisation problem will return a 401 error
· If the service is unavailable at the time the call was made a 500 error will return