Territory

_{Estimated reading time: 12 minutes}

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` - Polygon `1` - Circle `2` - 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`	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 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
- 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 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`	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 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`	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 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
    }
  ]
}

Overview​

Territory Object Fields​

Endpoints​

1. Create Territory​

Example:​

2. Get All Territories​

Example:​

3. Get a Territory by ID​

Example:​

4. Update a Territory​

Example:​

5. Delete Territories​

Example:​

6. Generate a Territory​

Example:​

7. Get Orders from Territory​

Overview

Territory Object Fields

Endpoints

1. Create Territory

Example:

2. Get All Territories

Example:

3. Get a Territory by ID

Example:

4. Update a Territory

Example:

5. Delete Territories

Example:

6. Generate a Territory

Example:

7. Get Orders from Territory