Manage Visibility Hub Places
- ser_hcskb_api
With the following API endpoints, you can Create, Read, Update and Delete Visibility Hub Places.
Visibility Hub Places can be used to define exact locations of stops, including custom geofence shapes and sizes as well as other features. For an overview, you can browse through our help center here.
Create new Places
To create new Visibility Hub Places, send a request to the following endpoint with the payload shown below:
PUT https://api.transporeon.com/rtv/v1/places/{place_reference_id}
{
"name": "Factory 01",
"address": {
"street_address": "1 Factory Street",
"city": "Paris",
"zipcode": 75001,
"country": "FR",
"name": "Factory S.A.",
"address_matching_disabled": false
},
"geometry": { //Defines the center of the Place' location
"type": "Point",
"coordinates": [
2.3522, //Longitude
48.8566 //Latitude
]
},
"geofence": { //CircleGeofence schema used
"type": "Feature",
"properties": {
"radius_in_meters": 200
},
"geometry": {
"type": "Point",
"coordinates": [
2.3522,
48.8566
]
}
}
}The address object is primarily used to display the Place's address components in the user interface. For details on the different address objects, read on.
Using different geofence geometries
The example above creates a Place with a circular geofence, defined in the CircleGeofence schema, radius 200 meters.
For all geofence definitions, the GeoJSON format is used: GeoJSON
Mind that for GeoJSON format, the order of coordinates in the tuple is [longitude, latitude].
To create a polygonal geofence, use the PolygonGeofence schema instead:
"geofence": { //PolygonGeofence schema used
"type": "Feature",
"geometry": {
"type": "Polygon",
"coordinates": [
[2.3522, 48.8566],
[2.3522, 48.855799],
[2.354739, 48.856038],
[2.3522, 48.8566]
]
}
}Note that a valid polygon according to the GeoJSON format must have at least 4 coordinate pairs, as the first and last pairs need to be the same to close the polygon shape.
Referring to a Place during transport creation
There are two ways to make use of created Places on creation of a transport:
Reference ID based matching
The explicit way to match incoming transport stops to Places:
Each Place has it’s own place_reference_id, that can be used to match a location of a transport to a Visibility Hub Place.
For details, see this help center article: Working with Places references
Address based matching
The implicit way to match incoming transport stop addresses to Places:
Visibility Hub uses the address data (street, house nr, city etc.) for a given transport stop to geocode the location (or alternatively, it’s possible to provide geocoordinates directly).
The address object in a Place can be used for matching incoming transport stop’s address data in order to make use of the Place’s definitions (ie. geofences and other features). If incoming transport stop address should not be used to match a given Place, the flag address_matching_disabled can be set to true (default: false).
Using address aliases
The default address of a Place can be specified with the address object shown in the example payload above.
As Visibility Hub also supports referring to Places by matching address data, additional addresses next to the default one can be specified in the address_aliases object as shown below:
"address_aliases": [
{
"street_address": "2 Factory Street",
"city": "Paris",
"zipcode": 75001,
"country": "FR",
"name": "Factory S.A., #2"
},
{
"street": "13 Warehouse Street",
"city": "Paris",
"zipcode": 75002,
"country": "FR",
"name": "Warehouse XYZ"
}
]Example: A transport is created that has a stop that matches one of the address_aliases shown above - the Place's definitions are used.
Receive existing Places
Existing Places can be fetched using one of the following two endpoints:
Receive a list of all Places, sorted by place_reference_id
GET https://api.transporeon.com/rtv/v1/places
Response
Receive a Place by place_reference_id
GET https://api.transporeon.com/rtv/v1/places/{place_reference_id}
Response
Update existing Places
To update an existing Place, simply use the same PUT endpoint as you have used for creating the Place. The Place entity is defined by the place_reference_id: When the place_reference_id already exists, the respective Place is updated instead of created.
Delete existing Places
To delete an existing Place, send a request to the following endpoint as shown below:
DELETE https://api.transporeon.com/rtv/v1/places/{place_reference_id}