Junction definition details
Purpose
Junction definition details is a REST API endpoint that reads static information about a selected junction. It contains the junction ID, name, status, and other static details of a selected junction.
The response can also, on demand, contain information about the junction model: junction boundary and its approaches and exits. It does not include any dynamic real-time data that is available using the Junction live data details and Junction live data list endpoints.
Request data
You can obtain the Junction definition details by sending a GET request, as shown in the following example.
- Constants and parameters enclosed in curly brackets { } must be replaced with their values.
- Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.
HTTPS method: GET
https://api.tomtom.com/junction-analytics/junctions/1/{junctionId}/definition?key={apiKey}&includeGeometry={includeGeometry}
Request parameters
The following table shows the query parameters:
- Required parameters must be used or the call will fail.
- Optional parameters may be used.
Required parameters | Description |
---|---|
junctionId string | The unique junction id that must be used in the request path. |
key string | An API Key valid for the requested service. Value: Your valid API Key. |
Optional parameters | Description |
---|---|
includeGeometry boolean | If true , the junction geometry is included in the response.Value: true or false |
Request headers
Header | Value |
---|---|
Content-Type | application/json |
If-Modified-Since | Optional, the date in the format of RFC 822, GMT. |
If-None-Match | Optional, the ETag value from a previous response. |
Example request
The following is an example curl request:
$ curl '/junction-analytics/junctions/1/{junctionId}/definition?key={apiKey}&includeGeometry={includeGeometry}' -i -X GET \-H 'Content-Type: application/json' \
Response data
This response returns junction definition details. The following table describes all of the fields that can appear in a response.
Response fields
Field | Description |
---|---|
id | Unique ID of the junction. |
name | The name of the junction as generated automatically, or provided in the junction definition creation request. |
status | One of the values: PREVIEW , ACTIVE , PENDING_UPDATE , ERROR . More details are available following this table. |
statusDetail | This appears in the case of an ERROR status, and provides further explanation. |
rawJunction | A GeoJson Feature, Polygon or Point (with the radius property).It contains the junction boundary used in the creation process. |
detectionConfig{} | Contains the detection configuration used in junction creation. |
detectionConfig.autodetectName | If true , the junction name was created based on its approaches. |
junctionModel{} | This contains junction geometry and other data. It is not available when the includeGeometry query param is false . Not available in ERROR status. |
junctionModel.name | The name of the junction as generated automatically, or provided in the junction definition creation request. |
junctionModel.countryCode | The three-letter country code defined in the ISO 3166-1 alpha-3 standard. |
junctionModel.driveOnLeft | This is a flag with information about left-hand traffic (LHT) or right-hand traffic (RHT). |
junctionModel.trafficLights | This is true if traffic lights are inside the creation area. |
junctionModel.approaches[] | Contains junction approaches. Min number of approaches: 1 |
junctionModel.approaches[].id | The approach ID is unique in the junction context. |
junctionModel.approaches[].name | Created based on the name and road direction. Example: "Some Street West Bound". |
junctionModel.approaches[].roadName | If the road has no name, it will be "Unnamed road". |
junctionModel.approaches[].direction | One of the values: SOUTH , WEST , EAST , NORTH , CLOCKWISE , COUNTER_CLOCKWISE . |
junctionModel.approaches[].frc | Functional Road Class. One of the values: 0 , 1 , 2 , 3 , 4 , 5 , 6 , 7 . |
junctionModel.approaches[].length | Length of the given approach in meters. |
junctionModel.approaches[].oneWayRoad | It is true if it is a one-direction road or not a single carriageway road. |
junctionModel.approaches[].excluded | Indicates that live data for the approach is collected. |
junctionModel.approaches[].drivable | Indicates if the road is drivable. |
junctionModel.approaches[].segmentedGeometry | Geometry of the given approach, split by map segments. See the GeoJson MultiLineString specification. |
junctionModel.approaches[].userPoints | Array of user-defined points that the geometry routes through. See the GeoJson Point specification. |
junctionModel.approaches[].openlr | Geometry of given approach, encoded into OpenLR format. See the OpenLR specification. |
junctionModel.exits[] | Contains junction exits. Min numbers of exits: 1. |
junctionModel.exits[].id | The exit ID is unique in the junction context. |
junctionModel.exits[].name | This is created based on the name and road direction. Example: "Typical Street West Bound". |
junctionModel.exits[].roadName | If the road has no name, it will be "Unnamed road". |
junctionModel.exits[].direction | One of the values: SOUTH , WEST , EAST , NORTH , CLOCKWISE , COUNTER_CLOCKWISE . |
junctionModel.exits[].frc | Functional Road Class. One of the values: 0 , 1 , 2 , 3 , 4 , 5 , 6 , 7 . |
junctionModel.exits[].oneWayRoad | It is true if it is a one-direction road or not a single carriageway road. |
junctionModel.exits[].drivable | Indicates ifthe road is drivable. |
junctionModel.exits[].segmentedGeometry | Geometry of the given exit, split by map segments. See the GeoJson MultiLineString specification. |
junctionModel.exits[].openlr | Geometry of the given exit, encoded into OpenLR format. See the OpenLR specification |
Junction status
The following table shows the junction status:
Value | Description |
---|---|
PREVIEW | Junction is processing, live data is not served. |
ACTIVE | Junction is processed, live data is served. |
PENDING_UPDATE | Junction is processing after update, live data is not served. |
ERROR | Something bad happened (an error occurred). |
Example response
The following JSON code block is an example response:
1{2 "id": "5fd9bb5a88a13608d7b5d92d",3 "name": "First Street - Second Street",4 "status": "ACTIVE",5 "rawJunction": {6 "type": "Feature",7 "properties": {},8 "geometry": {9 "type": "Polygon",10 "coordinates": [11 [12 [13 19.44755981778522,14 51.7275838542498415 ],16 [17 19.44698786140313,18 51.7270285079889319 ],20 [21 19.447606192627404,22 51.72621462614307623 ],24 [25 19.448688272269123,26 51.7269949954965427 ],28 [29 19.44755981778522,30 51.7275838542498431 ]32 ]33 ]34 }35 },36 "detectionConfig": {37 "autodetectName": false38 },39 "junctionModel": {40 "id": "19.4521-51.7766",41 "name": "First Street - Second Street",42 "countryCode": "DEU",43 "driveOnLeft": false,44 "trafficLights": true,45 "approaches": [46 {47 "id": 1397964518,48 "name": "First Street West Bound",49 "roadName": "First Street",50 "direction": "WEST",51 "frc": 7,52 "length": 192.77,53 "oneWayRoad": false,54 "excluded": false,55 "drivable": true,56 "segmentedGeometry": {57 "type": "MultiLineString",58 "coordinates": [59 [60 [61 19.45464,62 51.7771263 ],64 [65 19.45452,66 51.7771167 ],68 [69 19.45443,70 51.7770871 ]72 ]73 ]74 },75 "userPoints": [76 {77 "type": "Point",78 "coordinates": [79 19.45464,80 51.7771281 ]82 },83 {84 "type": "Point",85 "coordinates": [86 19.45443,87 51.7770888 ]89 }90 ],91 "openlr": "Cw3VGCTJOhJTB/5H/toWSXY=",92 "dataNotAvailable": false93 },94 {95 "id": -2036692957,96 "name": "Second Street North Bound",97 "roadName": "Second Street",98 "direction": "NORTH",99 "frc": 4,100 "length": 236.16,101 "oneWayRoad": true,102 "excluded": false,103 "drivable": true,104 "segmentedGeometry": {105 "type": "MultiLineString",106 "coordinates": [107 [108 [109 19.45265,110 51.77446111 ],112 [113 19.45224,114 51.77653115 ],116 [117 19.45224,118 51.77657119 ]120 ]121 ]122 },123 "userPoints": [124 {125 "type": "Point",126 "coordinates": [127 19.45265,128 51.77446129 ]130 },131 {132 "type": "Point",133 "coordinates": [134 19.45224,135 51.77657136 ]137 }138 ],139 "openlr": "Cw3VGCTJOhJTB/5H/toWSXY=",140 "dataNotAvailable": false141 }142 ],143 "exits": [144 {145 "id": 2032081462,146 "name": "First Street North Bound",147 "roadName": "First Street",148 "direction": "NORTH",149 "frc": 4,150 "oneWayRoad": false,151 "drivable": true,152 "segmentedGeometry": {153 "type": "MultiLineString",154 "coordinates": [155 [156 [157 19.45224,158 51.77657159 ],160 [161 19.45222,162 51.77665163 ]164 ]165 ]166 },167 "openlr": "Dw3VGCTJOhJTB/5H/toWSXY="168 },169 {170 "id": -351401112,171 "name": "Second Street East Bound",172 "roadName": "Second Street",173 "direction": "EAST",174 "frc": 7,175 "oneWayRoad": false,176 "drivable": true,177 "segmentedGeometry": {178 "type": "MultiLineString",179 "coordinates": [180 [181 [182 19.45224,183 51.77657184 ],185 [186 19.4525,187 51.77659188 ]189 ]190 ]191 },192 "openlr": "Ew3VGCTJOhJTB/5H/toWSXY="193 }194 ]195 }196}
Errors
The system generates an error response if there is an error in the supplied parameters or any other internal problem. This response is generated in the requested format.
HTTP error response codes
The following table shows the error response codes:
Code | Description |
---|---|
401 | Unauthorized |
403 | Forbidden |
404 | Not Found
|
Error response field
Field | Description |
---|---|
errorMessage | The problem description. |
Example error response
The following is an example error response:
1{2 "errorMessage": "Junction of id 5fd8da2b84510126b9d18b0d not found"3}