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 Summary Details

API Name

Geospatial API

Endpoint

https://fim.api.eu.fleetmatics.com/geo

Operation

GET, POST, PUT, DELETE

 

GET Methods

GET Geofences

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.

 

GET Geofence by Category

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.

 

GET Geofence by Category Sample Response

{

    "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"

                    }

                }

            }

        ]

    }

 

 

GET Geofences by Group ID

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.

 

GET Geofence by Group ID Sample Response

{

    "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": ""

                    }

                }

            },

 

GET Geofence by Category/Group ID Field Breakdown

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

GET Geofence by Place ID enables integration users to retrieve details regarding a specific Geofence.

 

GET Geofence by Place ID

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.

 

GET Geofence by Place ID Sample Response

{

    "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"

        }

    }

}

 

GET Geofence by Place ID Field Breakdown

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",

 

 

 

GET Geofence Spatial Data by Place ID

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.

 

GET Geofence Circle Spatial Data by Place ID

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.

 

GET Geofence Circle Spatial Data by Place ID Sample Response

{

    "ShapeType": "Circle",

    "Latitude": 41.396927,

    "Longitude": -81.455925,

    "RadiusInKm": 0.27561

}

 

 

GET Geofence Circle Spatial Data by Place ID Field Breakdown

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.

 

GET Geofence Rectangle Spatial Data by Place ID

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.

 

GET Geofence Rectangle Spatial Data by Place ID Sample Response

{

    "ShapeType": "Rectangle",

    "Latitude": 53.389422,

    "LengthInKm": 0.3130492799997731,

    "Longitude": -2.925248,

    "WidthInKm": -0.40642887541418127

}

 

GET Geofence Rectangle Spatial Data by Place ID Field Breakdown

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.

 

POST Methods

POST Circle Geofence

The POST Circle Geofence method is available to create circular Geofences within REVEAL. 

 

POST Circle Geofence Request Header

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.

 

POST Circle Geofence Request Business Rules

·      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.

 

POST Circle Geofence Sample Response

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.

 

POST Rectangle Geofence

The POST Rectangle Geofence method is available to create rectangular Geofences within REVEAL.

 

POST Rectangle Geofence Request Header

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.

 

 

 

 

 

 

 

 

POST Rectangle Geofence Request Business Rules

·      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.

 

POST Rectangle Geofence Sample Response

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

PUT Circle Geofence

The PUT Circle Geofence method is available to edit existing circular Geofences within REVEAL.

 

PUT Circle Geofence Request Header

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.

 

PUT Circle Geofence Request Business Rules

·      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 Circle Geofence Sample Response

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

 

PUT Rectangle Geofence

The PUT Rectangle Geofence method is available to edit existing rectangular Geofences within REVEAL.

 

PUT Rectangle Geofence Request Header

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.

 

PUT Rectangle Geofence Request Business Rules

·      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 Rectangle Geofence Sample Response

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

 

DELETE Methods

DELETE Geofence

The DELETE Geofence method is available for deleting any Geofence shape type from a REVEAL account.

 

DELETE Geofence Request Header

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.

 

DELETE Geofence Sample Response

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