Skip to main content
GuidesExamples

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

FieldTypeDescription
idIntegerUnique identifier for the miscellaneous location.
isDepotBooleanIndicates whether the location is a depot.
aliasStringShort name or identifier for the location.
addressObjectDetailed address information of the location.
locationObjectCoordinates 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 CodeDescription
200 SuccessfulSuccessful 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 UnauthorizedAPI key is missing or invalid.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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 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)
{
"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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestInvalid input or missing required fields.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundMiscLocation not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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 CodeDescription
200 SuccessfulSuccessful 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 UnauthorizedAPI key is missing or invalid.
404 Not FoundMiscLocation not found in database.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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 CodeDescription
200 SuccessfulSuccessful operation.
400 Bad RequestInvalid input or missing required fields.
401 UnauthorizedAPI key is missing or invalid.
404 Not FoundCan't delete misc locations because at least one of them does not exist.
405 Method Not AllowedIncorrect method type.
500 Internal Server ErrorDatabase 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",
}