Territory
Overview
The Territory RestAPI allows you to manage territories within the Fleet Management system. You can create, retrieve, update, and delete territories. This RestAPI supports basic operations to define geographical regions used for route planning and optimization.
Territory Object Fields
Field | Type | Description |
---|---|---|
id | Integer | Unique identifier for the territory. |
name | String | Name of the territory. |
type | Integer | Territory type: 0 - Polygon1 - Circle2 - Rectangle |
data | Array | Defines the shape of the territory based on its type: Circle - Contains the center and a point on the circle. Rectangle - Contains two diagonally opposite points. Polygon - Contains a list of points defining the area. |
color | String | Color associated with the territory. |
orders | Array | List of orders associated with the territory. |
Endpoints
1. Create Territory
Description: Adds a new territory to the database.
- Method:
POST
- Endpoint:
/territories
- Headers:
Authorization: YOUR_API_KEY
Content-Type: application/json
- URL:
https://fleetmanagement.magiclaneapis.com/v1/territories
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
400 Bad Request |
|
401 Unauthorized | API key is missing or invalid. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Example:
- Request Body:
[
{
"name": "North Region",
"type": 1,
"data": [
[
48.827865,
2.379216
],
[
48.43446,
5.234103
]
],
"color": "#FF5733"
},
{
"name": "South Region",
"type": 2,
"data": [
[
48.88025,
2.299601
],
[
48.897163,
2.292865
],
[
46.199373,
0.069986
],
[
47.602138,
2.330583
]
],
"color": "#FF5723"
}
]
- Response Body: (error code
200
)
{
"territories": [
{
"name": "North Region",
"type": 1,
"data": [
[
48.827865,
2.379216
],
[
48.43446,
5.234103
]
],
"color": "#FF5733",
"orders": [
{
"id": 879887,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838721,
"alias": "Magic Customer",
"firstName": "Magic",
"lastName": "Customer",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.870852,
2.356148
],
"alias": "Magic Order",
"firstName": "Magic",
"lastName": "Order",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555018",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"revenue": 12,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
},
{
"id": 879888,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838722,
"alias": "Magic Customer2",
"firstName": "Magic",
"lastName": "Customer2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer2@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.827865,
2.379216
],
"alias": "Magic Order2",
"firstName": "Magic2",
"lastName": "Order2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555019",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 2,
"weight": 4.5,
"cube": 1.1,
"revenue": 16,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
}
]
},
{
"name": "South Region",
"type": 2,
"data": [
[
48.88025,
2.299601
],
[
48.897163,
2.292865
],
[
46.199373,
0.069986
],
[
47.602138,
2.330583
]
],
"color": "#FF5723",
"orders": []
}
]
}
2. Get All Territories
Description: Fetches a list of all territories.
- Method:
GET
- Endpoint:
/territories
- Headers:
Authorization: YOUR_API_KEY
- URL:
https://fleetmanagement.magiclaneapis.com/v1/territories
- Query Parameters:
search
(string, optional) – General search term across territories.id
(string, optional) – Filter by territory ID (id=value:exact
for exact match).name
(string, optional) – Filter by territory name (name=value:exact
for exact match).type
(string, optional) – Filter by territory type (type=value
).data
(string, optional) – Filter by data (data=value:exact
for exact match).color
(string, optional) – Filter by color (color=value:exact
for exact match).sort
(string, optional) – Sorting format:column1:asc/desc,column2:asc/desc
- Available columns:
id, name, type, data, color
- Available columns:
includeColumns
(string, optional) – Specify which columns to include.- Available columns:
id, name, type, data, color
- Available columns:
page
(integer, optional) – Page number for pagination.per_page
(integer, optional) – Number of items per page.
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
400 Bad Request | The values sent for page and per_page parameters are incorrect; should be greater than 0. |
401 Unauthorized | API key is missing or invalid. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Example:
- Response Body: (error code
200
)
{
"territories": [
{
"name": "North Region",
"type": 1,
"data": [
[
48.827865,
2.379216
],
[
48.43446,
5.234103
]
],
"color": "#FF5733",
"orders": [
{
"id": 879887,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838721,
"alias": "Magic Customer",
"firstName": "Magic",
"lastName": "Customer",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.870852,
2.356148
],
"alias": "Magic Order",
"firstName": "Magic",
"lastName": "Order",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555018",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"revenue": 12,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
},
{
"id": 879888,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838722,
"alias": "Magic Customer2",
"firstName": "Magic",
"lastName": "Customer2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer2@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.827865,
2.379216
],
"alias": "Magic Order2",
"firstName": "Magic2",
"lastName": "Order2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555019",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 2,
"weight": 4.5,
"cube": 1.1,
"revenue": 16,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
}
]
},
{
"name": "South Region",
"type": 2,
"data": [
[
48.88025,
2.299601
],
[
48.897163,
2.292865
],
[
46.199373,
0.069986
],
[
47.602138,
2.330583
]
],
"color": "#FF5723",
"orders": []
}
]
}
3. Get a Territory by ID
Description: Retrieves a specific territory by ID.
- Method:
GET
- Endpoint:
/territories/{id}
- Headers:
Authorization: Bearer YOUR_API_KEY
- URL:
https://fleetmanagement.magiclaneapis.com/v1/territories/{id}
- Path Parameter:
id
(integer, *required) - The unique territory ID.
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
400 Bad Request | Invalid input or missing required fields. |
401 Unauthorized | API key is missing or invalid. |
404 Not Found | Territory not found in database. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Example:
- Response Body: (error code
200
)
4. Update a Territory
Description: Updates an existing territory record.
- Method:
PUT
- Endpoint:
/territories/{id}
- Headers:
Authorization: YOUR_API_KEY
Content-Type: application/json
- URL:
https://fleetmanagement.magiclaneapis.com/v1/territories/{id}
- Path Parameter:
id
(integer, *required) - Territory ID.
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
400 Bad Request |
|
401 Unauthorized | API key is missing or invalid. |
404 Not Found | Territory not found in database. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Example:
- Request Body:
- Response Body: (error code
200
)
{
"message": "Operation done successfully",
}
5. Delete Territories
Description: Deletes territories from the system.
- Method:
DELETE
- Endpoint:
/territories
- Headers:
Authorization: YOUR_API_KEY
Content-Type: application/json
- URL:
https://fleetmanagement.magiclaneapis.com/v1/territories
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
401 Unauthorized | API key is missing or invalid. |
404 Not Found | Can't delete territories because at least one of them does not exist |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Example:
- Request Body:
{
"ids": [1234, 5678]
}
- Response Body: (error code
200
)
{
"message": "Operation done successfully",
}
6. Generate a Territory
Description: Automatically generates a territory based on provided parameters.The list of coordinates should contain at least 3 coordinates to create 1 territory. TerritoriesNumber, how many territories should be created (if is is 0, then the algorithm will determinate how many should be created).
- Method:
POST
- Endpoint:
/territories/generate
- Headers:
Authorization: YOUR_API_KEY
Content-Type: application/json
- URL:
https://fleetmanagement.magiclaneapis.com/v1/territories/generate
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
400 Bad Request |
|
401 Unauthorized | API key is missing or invalid. |
404 Not Found | Couldn't create that many territories. Try adding more coordinates or lower the number of territories. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
Example:
- Request Body:
{
"locations": [
[
48.870852,
2.356148
],
[
48.827327,
2.342267
],
[
48.88025,
2.299601
],
[
48.845198,
2.402896
],
[
48.887096,
2.283513
],
[
48.896894,
2.321586
],
[
48.870449,
2.342204
],
[
48.895658,
2.344043
],
[
48.458357,
-0.054451
],
[
45.049782,
2.475759
],
[
46.199373,
0.069986
],
[
47.602138,
2.330583
],
[
44.346051,
4.694878
],
[
44.464582,
2.45502
],
[
48.43446,
5.234103
],
[
49.161539,
0.50058
]
],
"territoriesNumber": 3
}
- Response Body: (error code
200
)
{
"territories": [
{
"id": 879888,
"name": "Territory 0",
"type": 0,
"data": [
[
44.464582,
2.45502
],
[
48.887096,
2.283513
],
[
48.896894,
2.321586
],
[
48.870449,
2.342204
],
[
48.895658,
2.344043
]
],
"color": "#FF5733"
},
{
"id": 879887,
"name": "Territory 1",
"type": 0,
"data": [
[
49.161539,
0.50058
],
[
44.346051,
4.694878
],
[
48.870852,
2.356148
],
[
48.827327,
2.342267
],
[
48.88025,
2.299601
],
[
48.845198,
2.402896
]
],
"color": "#FF5723"
},
{
"id": 879886,
"name": "Territory 2",
"type": 0,
"data": [
[
48.43446,
5.234103
],
[
48.458357,
-0.054451
],
[
45.049782,
2.475759
],
[
46.199373,
0.069986
],
[
47.602138,
2.330583
]
],
"color": "#FF5743"
}
]
}
7. Get Orders from Territory
Description: Retrieves all orders assigned to a specific territory.
- Method:
GET
- Endpoint:
/territories/{id}/orders
- Headers:
Authorization: YOUR_API_KEY
- URL:
https://fleetmanagement.magiclaneapis.com/v1/territories/{id}/orders
- Path Parameter:
id
(integer, *required) - The unique territory ID.
- Returned error codes:
Error Code | Description |
---|---|
200 Successful | Successful operation. |
401 Unauthorized | API key is missing or invalid. |
404 Not Found | Territory not found in database. |
405 Method Not Allowed | Incorrect method type. |
500 Internal Server Error | Database error occurred. |
- Response Body: (error code
200
)
{
"orders": [
{
"id": 879887,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838721,
"alias": "Magic Customer",
"firstName": "Magic",
"lastName": "Customer",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.870852,
2.356148
],
"alias": "Magic Order",
"firstName": "Magic",
"lastName": "Order",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555018",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 3,
"weight": 5.1,
"cube": 2.5,
"revenue": 12,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
},
{
"id": 879888,
"creationTimestamp": 1751445531350,
"customerInfo": {
"id": 1838722,
"alias": "Magic Customer2",
"firstName": "Magic",
"lastName": "Customer2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"email": "magiccustomer2@example.com",
"phoneNumber": "+1202555018",
"location": [
48.870852,
2.356148
],
"customData": ""
},
"location": [
48.827865,
2.379216
],
"alias": "Magic Order2",
"firstName": "Magic2",
"lastName": "Order2",
"address": {
"country": "",
"state": "",
"county": "",
"city": "",
"postalCode": "",
"streetName": "",
"streetNumber": ""
},
"phoneNumber": "+1202555019",
"customData": "",
"type": 0,
"status": 0,
"state": 1,
"priority": 0,
"numberOfPackages": 2,
"weight": 4.5,
"cube": 1.1,
"revenue": 16,
"timeWindow": [
420,
1086
],
"serviceTime": 0,
"depotId": 0
}
]
}