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.us.fleetmatics.com/geo/v1/geofences?categoryName=<CategoryName>
HTTP/1.1 |
HOST |
fim.api.us.fleetmatics.com |
Accept |
application/json |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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.us.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.us.fleetmatics.com/GSM/v1/geofences/JC123"
},
"spatialdata": {
"href":
"http://api.us.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.us.fleetmatics.com/geo/v1/geofences?groupId=<groupID>
HTTP/1.1 |
HOST |
fim.api.us.fleetmatics.com |
Accept |
application/json |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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.us.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.us.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.us.fleetmatics.com:443/geo/v1/geofences/<PlaceID>
HTT/1.1 |
HOST |
fim.api.us.fleetmatics.com |
Accept |
application/json |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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.us.fleetmatics.com/GSM/v1/geofences/369852"
},
"spatialdata": {
"href":
"http://api.us.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.us.fleetmatics.com/geo/v1/geofences/circles/<PlaceID>/spatialdata
HTTP/1.1 |
HOST |
fim.api.us.fleetmatics.com |
Accept |
application/json |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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.us.fleetmatics.com/geo/v1/geofences/rectangles/<PlaceID>/spatialdata
HTTP/1.1 |
HOST |
fim.api.us.fleetmatics.com
|
Accept |
application/json |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[
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.us.fleetmatics/geo/v1/geofences/circles
HTTP/1.1 |
HOST |
fim.api.us.fleetmatics.com |
Accept |
application/json |
Content-Length |
This value will auto-calculate based on the Content provided for
the Geofence details. |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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.us.fleetmatics.com/geo/v1/geofences/rectangles HTTP/1.1 |
HOST |
fim.api.us.fleetmatics.com |
Accept |
application/json |
Content-Length |
This value will auto-calculate based on the Content provided for
the Geofence details. |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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.
The PUT Circle Geofence method is available to edit existing circular Geofences within REVEAL.
Operation and Path |
PUT https://fim.api.us.fleetmatics.com/geo/v1/geofences/circles/<PlaceID>
HTTP/1.1 |
HOST |
fim.api.us.fleetmatics.com |
Accept |
application/json |
Content-Length |
This value will auto-calculate based on the Content provided for
the Geofence details. |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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 Authorization 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.us.fleetmatics.com/geo/v1/geofences/rectangles/ <PlaceID> HTTP/1.1 |
HOST |
fim.api.us.fleetmatics.com |
Accept |
application/json |
Content-Length |
This value will auto-calculate based on the Content provided for
the Geofence details. |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[ 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 Authorization 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.us.fleetmatics.com/geo/v1/geofences/<PlaceID>
HTTP/1.1 |
HOST |
fim.api.us.fleetmatics.com
|
Accept |
application/json |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-us-[
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 Authorization problem will return a 401 error
· If the service is unavailable at the time the call was made a 500 error will return