Junction manual update

Service version: v1
Last edit: 2023.10.12

Purpose

The Junction Manual Update is a specialized REST API endpoint designed to provide a customized way to update junctions. Through this endpoint, users can manually define the properties of the junction.

Features

  • Selective Approaches: The endpoint supports the deactivation of approaches that are not required by the customer.

Workflow

  1. Junction Definition Preview:

    • Before proceeding with the manual update of the junction, utilize the Junction Definition Preview to visualize and review the proposed junction.
  2. Prepare Request:

    • The response from the Junction Definition Preview contains essential fields (junction, approaches, exits) that should be included in the Junction Definition Manual Update request.
  3. Receive Response:

    • Upon successful submission, the response will provide a unique junction ID.

Request data

To manually update the junction, issue a PUT request as demonstrated in the following example. Ensure you adhere to the specified request format for successful updates.

  • 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 parameter tables for their values. The generic request format is as follows.

HTTPS method: PUT

put
URL request example
https://api.tomtom.com/junction-analytics/junctions/1/{junctionId}/definition/manual?key={Your_API_Key}

PUT request body example

put
PUT request body example - JSON
1{
2 "name": "Otto-Braun-Straße - Karl-Marx-Allee - Alexanderstraße",
3 "detectionConfig": {
4 "autodetectName": true
5 },
6 "junction": {
7 "type": "Feature",
8 "geometry": {
9 "type": "Point",
10 "coordinates": [
11 13.41649420385599,
12 52.52202006909155
13 ]
14 },
15 "properties": {
16 "radius": 51.30814890800801
17 }
18 },
19 "approaches": [
20 {
21 "id": -1194621510,
22 "segmentedGeometry": {
23 "type": "MultiLineString",
24 "coordinates": [
25 [
26 [
27 13.41808,
28 52.52377
29 ],
30 [
31 13.41775,
32 52.52348
33 ]
34 ],
35 [
36 [
37 13.41775,
38 52.52348
39 ],
40 [
41 13.41704,
42 52.52285
43 ]
44 ]
45 ]
46 },
47 "excluded": false
48 },
49 {
50 "id": 1275645260,
51 "segmentedGeometry": {
52 "type": "MultiLineString",
53 "coordinates": [
54 [
55 [
56 13.41958,
57 52.5212
58 ],
59 [
60 13.41889,
61 52.52141
62 ]
63 ],
64 [
65 [
66 13.41889,
67 52.52141
68 ],
69 [
70 13.41871,
71 52.52146
72 ]
73 ]
74 ]
75 },
76 "excluded": false
77 }
78 ],
79 "exits": [
80 {
81 "segmentedGeometry": {
82 "type": "MultiLineString",
83 "coordinates": [
84 [
85 [
86 13.41599,
87 52.52178
88 ],
89 [
90 13.41576,
91 52.52155
92 ]
93 ]
94 ]
95 }
96 },
97 {
98 "segmentedGeometry": {
99 "type": "MultiLineString",
100 "coordinates": [
101 [
102 [
103 13.41641,
104 52.52223
105 ],
106 [
107 13.41625,
108 52.5223
109 ]
110 ]
111 ]
112 }
113 }
114 ]
115}

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.

Post request body fields

Field

Description

name
string

Name for a updated junction.
Not required by default.
Take a look at detectionConfig.autodetectName.
Maximum length is 250 characters.

detectionConfig
object

Contains the detection configuration used in junction update.

detectionConfig.autodetectName
boolean

If true, the junction name will be updated based on its approaches.
If false, the name field is required.
**Default value: ** true

junction
object

Required

A GeoJSON Feature, Polygon, or Point (with the radius property).


It contains the junction boundary that will be used in the update process.

approaches[]


array

Contains junction approaches. Minimum number of approaches: 1.


The details in this section are derived from the Junction Definition Preview.

approaches[].id


integer

The approach ID is unique in the junction context.

approaches[].excluded


boolean

Indicates that live data for the approach is collected.

approaches[].segmentedGeometry


object

Geometry of the given approach, split by map segments. See the GeoJSON MultiLineString specification.

exits[]


array

Contains junction exits.


Minimum numbers of exits: 1.


The details in this section are derived from the Junction Definition Preview.

junctionModel.exits[].segmentedGeometry


object

Geometry of the given exit, split by map segments. See the GeoJSON MultiLineString specification.

Request headers

Header

Value

Content-Type

application/json

Example request

The following is an example curl request:

put
curl command example
1$ curl '/junction-analytics/junctions/1/5fd8da2b84510126b9d18b0d/definition/manual?key={Your_API_Key}' -i -X PUT -d '{
2 "name": "Otto-Braun-Straße - Karl-Marx-Allee - Alexanderstraße",
3 "detectionConfig": {
4 "autodetectName": true
5 },
6 "junction": {
7 "type": "Feature",
8 "geometry": {
9 "type": "Point",
10 "coordinates": [
11 13.41649420385599,
12 52.52202006909155
13 ]
14 },
15 "properties": {
16 "radius": 51.30814890800801
17 }
18 },
19 "approaches": [
20 {
21 "id": -1194621510,
22 "segmentedGeometry": {
23 "type": "MultiLineString",
24 "coordinates": [
25 [
26 [
27 13.41808,
28 52.52377
29 ],
30 [
31 13.41775,
32 52.52348
33 ]
34 ],
35 [
36 [
37 13.41775,
38 52.52348
39 ],
40 [
41 13.41704,
42 52.52285
43 ]
44 ]
45 ]
46 },
47 "excluded": false
48 },
49 {
50 "id": 1275645260,
51 "segmentedGeometry": {
52 "type": "MultiLineString",
53 "coordinates": [
54 [
55 [
56 13.41958,
57 52.5212
58 ],
59 [
60 13.41889,
61 52.52141
62 ]
63 ],
64 [
65 [
66 13.41889,
67 52.52141
68 ],
69 [
70 13.41871,
71 52.52146
72 ]
73 ]
74 ]
75 },
76 "excluded": false
77 }
78 ],
79 "exits": [
80 {
81 "segmentedGeometry": {
82 "type": "MultiLineString",
83 "coordinates": [
84 [
85 [
86 13.41599,
87 52.52178
88 ],
89 [
90 13.41576,
91 52.52155
92 ]
93 ]
94 ]
95 }
96 },
97 {
98 "segmentedGeometry": {
99 "type": "MultiLineString",
100 "coordinates": [
101 [
102 [
103 13.41641,
104 52.52223
105 ],
106 [
107 13.41625,
108 52.5223
109 ]
110 ]
111 ]
112 }
113 }
114 ]
115}'

Response data

This response returns the junction ID and modification type. The following table describes all of the fields that can appear in a response.

Example response

The following JSON code block is an example response:

Response body - JSON
1{
2 "modificationType": "Updated",
3 "junctionId": "65268ff77cd5d952a185b9b5"
4}

Response fields

The following table describes all of the fields that can appear in a response.

Field

Description

modificationType


string

String that describes the modification type. In this case it has the value Updated.

junctionId


string

Unique ID of the updated junction.

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.

Error response codes

The following table shows the HTTP error response codes.

Code

Description

401

Unauthorized

403

Forbidden

400

Bad Request

Example messages:

  • Junctions limit of 10 is reached. Remove some of your existing junctions or contact support.
  • 'junction' field is required.
  • Name should be provided if detectionConfig.autodetectName is set to false!
  • Name should not be empty or consist of only whitespace!
  • Junction name TestJunction exceeded maximum length of 250.
  • We're having trouble creating the junction. This issue is noted in the system, please try later.
  • Maximum area of 1 km2 exceeded.
  • Maximum area boundary length of 3000 meters exceeded.
  • Maximum radius of 500 meters exceeded.
  • Circle radius can't be empty.
  • A junction that crosses countries is unsupported; attempted POL, DEU.

Error response field

Field

Description

message


string

The problem description.

Example error response

The following is an example error response:

Response error message - JSON
1{
2 "message": "Name should be provided if detectionConfig.autodetectName is set to false!"
3}