Miscellaneous Location

_{Estimated reading time: 9 minutes}

Overview

The Miscellaneous Location RestAPI allows you to manage miscellaneous locations within the Fleet Management system. You can create, retrieve, update, and delete miscellaneous locations. This API supports filtering, sorting, and pagination to help manage large datasets efficiently.

Miscellaneous Location Object Fields

Field	Type	Description
id	Integer	Unique identifier for the miscellaneous location.
isDepot	Boolean	Indicates whether the location is a depot.
alias	String	Short name or identifier for the location.
address	Object	Detailed address information of the location.
location	Object	Coordinates of the miscellaneous location.

---

Endpoints

1. Create Miscellaneous Location

Description: Adds a new miscellaneous location to the database.

• Method: POST
• Endpoint: /misc-locations
• Headers:
  • Authorization: YOUR_API_KEY
  • Content-Type: application/json
• URL: https://fleetmanagement.magiclaneapis.com/v1/misc-locations
• Returned error codes:

Error Code	Description
200 Successful	Successful operation.
400 Bad Request	The miscLocation does not have the coordinates set. Please try to set a correct set of coordinates. The miscLocation is curently used in another operation.
401 Unauthorized	API key is missing or invalid.
405 Method Not Allowed	Incorrect method type.
500 Internal Server Error	Database error occurred.

Note

If the operation is successful, the Miscellaneous Location object will have its id field populated. If the operation fails, an error code is returned, which can be interpreted as described in the Returned error codes section.

Example:

• Request Body:

[
  {
    "isDepot": true,
    "alias": "Depot 1",
    "location": [
      48.870569,
      2.356448
    ],
    "address": {
      "country": "France",
      "state": "Ile-de-France",
      "county": "Paris",
      "city": "Paris",
      "postalCode": "75001",
      "streetName": "Rue de Rivoli",
      "streetNumber": "1"
    }
  },
  {
    "isDepot": true,
    "alias": "Depot 2",
    "location": [
      45.652871,
      25.585588
    ],
    "address": {
      "country": "France",
      "state": "Aquitaine",
      "county": "Aquitaine",
      "city": "Bordeaux",
      "postalCode": "33300",
      "streetName": "Jean Jaures",
      "streetNumber": "82"
    }
  }
]

• Response Body: (error code 200)

{
  "miscLocations": [
    {
      "id": 16262,
      "isDepot": true,
      "alias": "Depot 1",
      "location": [
        48.870569,
        2.356448
      ],
      "address": {
        "country": "France",
        "state": "Ile-de-France",
        "county": "Paris",
        "city": "Paris",
        "postalCode": "75001",
        "streetName": "Rue de Rivoli",
        "streetNumber": "1"
      }
    },
    {
      "id": 16263,
      "isDepot": true,
      "alias": "Depot 2",
      "location": [
        45.652871,
        25.585588
      ],
      "address": {
        "country": "France",
        "state": "Aquitaine",
        "county": "Aquitaine",
        "city": "Bordeaux",
        "postalCode": "33300",
        "streetName": "Jean Jaures",
        "streetNumber": "82"
      }
    }
  ]
}

---

2. Get All Miscellaneous Location

Description: Fetches a list of all miscellaneous locations with optional filtering.

• Method: GET
• Endpoint: /misc-locations
• Headers:
  • Authorization: YOUR_API_KEY
• URL: https://fleetmanagement.magiclaneapis.com/v1/misc-locations
• Query Parameters:
  • search (string, optional) – General search term across miscLocations.
  • id (string, optional) – Filter by miscLocation ID (id=value:exact for exact match).
  • alias (string, optional) – Filter by miscLocation alias (alias=value:exact for exact match).
  • location (string, optional) – Filter by location (location=value:exact for exact match).
  • country (string, optional) – Filter by country (country=value:exact for exact match).
  • state (string, optional) – Filter by state (state=value:exact for exact match).
  • county (string, optional) – Filter by county (county=value:exact for exact match).
  • city (string, optional) – Filter by city (city=value:exact for exact match).
  • postalCode (string, optional) – Filter by postal code (postalCode=value:exact for exact match).
  • streetName (string, optional) – Filter by street name (streetName=value:exact for exact match).
  • streetNumber (string, optional) – Filter by street number (streetNumber=value:exact for exact match).
  • extra (string, optional) – Filter by extra address value (extra=value:exact for exact match).
  • sort (string, optional) – Sorting format: column1:asc/desc,column2:asc/desc
    • Available columns: id, isDepot, alias, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra
  • includeColumns (string, optional) – Specify which columns to include.
    • Available columns: id, isDepot, alias, latitude, longitude, country, state, county, city, postalCode, streetName, streetNumber, extra
  • 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)

{
  "miscLocations": [
    {
      "id": 16262,
      "isDepot": true,
      "alias": "Depot 1",
      "location": [
        48.870569,
        2.356448
      ],
      "address": {
        "country": "France",
        "state": "Ile-de-France",
        "county": "Paris",
        "city": "Paris",
        "postalCode": "75001",
        "streetName": "Rue de Rivoli",
        "streetNumber": "1"
      }
    },
    {
      "id": 16263,
      "isDepot": true,
      "alias": "Depot 2",
      "location": [
        45.652871,
        25.585588
      ],
      "address": {
        "country": "France",
        "state": "Aquitaine",
        "county": "Aquitaine",
        "city": "Bordeaux",
        "postalCode": "33300",
        "streetName": "Jean Jaures",
        "streetNumber": "82"
      }
    }
  ]
}

---

3. Get a Miscellaneous Location by ID

Description: Retrieves a specific miscellaneous location by ID.

• Method: GET
• Endpoint: /misc-locations/{id}
• Headers: - Authorization: YOUR_API_KEY
• URL: https://fleetmanagement.magiclaneapis.com/v1/misc-locations/{id}
• Path Parameter:
  • id (integer, *required) - The unique location 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	MiscLocation not found in database.
405 Method Not Allowed	Incorrect method type.
500 Internal Server Error	Database error occurred.

Example:

• Response Body: (error code 200)

{
  "id": 16262,
  "isDepot": true,
  "alias": "Depot 1",
  "location": [
    48.870569,
    2.356448
  ],
  "address": {
    "country": "France",
    "state": "Ile-de-France",
    "county": "Paris",
    "city": "Paris",
    "postalCode": "75001",
    "streetName": "Rue de Rivoli",
    "streetNumber": "1"
  }
}

---

4. Update a Miscellaneous Location

Description: Updates an existing miscellaneous location record.

• Method: PUT
• Endpoint: /misc-locations/{id}
• Headers:
  • Authorization: YOUR_API_KEY
  • Content-Type: application/json
• URL: https://fleetmanagement.magiclaneapis.com/v1/misc-locations/{id}
• Path Parameter:
  • id (integer, *required) - The unique location ID.
• Returned error codes:

Error Code	Description
200 Successful	Successful operation.
400 Bad Request	The miscLocation does not have the coordinates set. Please try to set a correct set of coordinates. The miscLocation is curently used in another operation.
401 Unauthorized	API key is missing or invalid.
404 Not Found	MiscLocation not found in database.
405 Method Not Allowed	Incorrect method type.
500 Internal Server Error	Database error occurred.

Example:

• Request Body:

{
  "id": 16262,
  "isDepot": true,
  "alias": "Depot 1",
  "location": [
    48.870569,
    2.356448
  ],
  "address": {
    "country": "France",
    "state": "Ile-de-France",
    "county": "Paris",
    "city": "Paris",
    "postalCode": "75001",
    "streetName": "Rue de Rivoli",
    "streetNumber": "1"
  }
}

• Response Body: (error code 200)

{
  "message": "Operation done successfully",
}

---

5. Delete MiscLocations

Description: Deletes miscellaneous locations.

• Method: DELETE
• Endpoint: /misc-locations
• Headers:
  • Authorization: YOUR_API_KEY
• URL: https://fleetmanagement.magiclaneapis.com/v1/misc-locations
• 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	Can't delete misc locations because at least one of them does not exist.
405 Method Not Allowed	Incorrect method type.
500 Internal Server Error	Database error occurred.

Note

If a miscellaneous location that needs to be deleted was previously used to create orders or as a departure point, the id_depot in those orders or the departure field will be set to 0.

Example:

• Request Body:

   [98765, 98766, 98767 ]

• Response Body: (error code 200)

{
  "message": "Operation done successfully",
}

---