Skip to main content
GuidesAPI ReferenceExamples

Territory

|

The Territory Rest API allows you to manage territories within the Fleet Management system. You can create, retrieve, update, and delete territories. This Rest API supports basic operations to define geographical regions used for route planning and optimization.

Territory Object Fields​

FieldTypeDescription
idIntegerUnique identifier for the territory.
nameStringName of the territory.
typeInteger
Territory type:
0 - Polygon
1 - Circle
2 - Rectangle
dataArray
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.
colorStringColor associated with the territory.
ordersArrayList 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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad Request
  • Not all the points of the territory's data have 2 values (latitude, longitude).
  • For polygon, the data should have 3 points; for circle and rectangle the territory’s data should have 2 points: the center of the circle and a point on the circle edge or 2 points diagonally opposite.
401 UnauthorizedAPI key is missing or invalid.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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": 1763486363160,
          "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": 1763486363160,
          "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
    • includeColumns (string, optional) – Specify which columns to include.
      • Available columns: id, name, type, data, color
    • page (integer, optional) – Page number for pagination.
    • per_page (integer, optional) – Number of items per page.
  • Returned error codes:
Error CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestThe values sent for page and per_page parameters are incorrect; should be greater than 0.
401 UnauthorizedAPI key is missing or invalid.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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": 1763486363160,
          "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": 1763486363160,
          "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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestInvalid input or missing required fields.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundTerritory not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.

Example:​

  • Response Body: (error code 200)
{
  "name": "North Region",
  "type": 1,
  "data": [
    [
      48.827865,
      2.379216
    ],
    [
      48.43446,
      5.234103
    ]
  ],
  "color": "#FF5733",
  "orders": [
    {
      "id": 879887,
      "creationTimestamp": 1763486363160,
      "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": 1763486363160,
      "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
    }
  ]
}

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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad Request
  • Not all the points of the territory's data have 2 values (latitude, longitude).
  • For polygon, the data should have 3 points; for circle and rectangle the territory’s data should have 2 points: the center of the circle and a point on the circle edge or 2 points diagonally opposite.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundTerritory not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.

Example:​

  • Request Body:
{
  "name": "North Region",
  "type": 1,
  "data": [
    [
      48.827865,
      2.379216
    ],
    [
      48.43446,
      5.234103
    ]
  ],
  "color": "#FF5733",
  "orders": [
    {
      "id": 879887,
      "creationTimestamp": 1763486363160,
      "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": 1763486363160,
      "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
    }
  ]
}
  • 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 CodeDescription
200 SuccessfulSuccessful operation.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundCan't delete territories because at least one of them does not exist
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad Request
  • The number of locations is less than 3 and a territory needs at least 3 locations.
  • The number of locations should be at least three times the number of territories.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundCouldn't create that many territories. Try adding more coordinates or lower the number of territories.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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 CodeDescription
200 SuccessfulSuccessful operation.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundTerritory not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase error occurred.
  • Response Body: (error code 200)
{
  "orders": [
    {
      "id": 879887,
      "creationTimestamp": 1763486363160,
      "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": 1763486363160,
      "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
    }
  ]
}
Last updated on