Skip to main content

​
Overview

The Locations API allows you to manage physical locations, facilities, and bases. Locations are associated with companies and can be designated as main bases.

​
Location Object

The Location type represents a physical location or facility.
​
id
number
required
Unique identifier for the location
​
name
string
required
Location name
​
address
string
required
Physical address of the location
​
type
string
required
Type of location (e.g., “BASE”, “HANGAR”, “OFFICE”, “WAREHOUSE”)
​
isMainBase
boolean
required
Whether this location is designated as a main base
​
cod_iata
string
required
IATA code (International Air Transport Association) for the location
​
companies
Company[]
required
Array of companies that operate at this location

​
List Locations

Retrieve a list of all locations in the system. 
import axiosInstance from '@/lib/axios';
import { Location } from '@/types';

const fetchLocations = async (): Promise<Location[]> => {
  const { data } = await axiosInstance.get('/locations');
  return data;
};

​
Response

[
  {
    "id": 1,
    "name": "Caracas Main Base",
    "address": "Aeropuerto Internacional Simón Bolívar, Maiquetía",
    "type": "BASE",
    "isMainBase": true,
    "cod_iata": "CCS",
    "companies": [
      {
        "id": 1,
        "name": "SIGEAC Airlines",
        "description": "Main aviation company",
        "slug": "sigeac-airlines",
        "cod_iata": "SGC",
        "cod_oaci": "SGAC"
      }
    ]
  },
  {
    "id": 2,
    "name": "Maracaibo Hangar",
    "address": "Aeropuerto La Chinita, Maracaibo",
    "type": "HANGAR",
    "isMainBase": false,
    "cod_iata": "MAR",
    "companies": [
      {
        "id": 1,
        "name": "SIGEAC Airlines",
        "slug": "sigeac-airlines"
      }
    ]
  }
]

​
Get Location by ID

Retrieve a specific location by its ID. 
const fetchLocationById = async (locationId: number): Promise<Location> => {
  const { data } = await axiosInstance.get(`/locations/${locationId}`);
  return data;
};

​
Parameters

​
locationId
number
required
The unique identifier of the location

​
Locations by Company

Retrieve locations belonging to a specific company.

​
By Company ID

const fetchLocationsByCompany = async (companyId: number): Promise<Location[]> => {
  const { data } = await axiosInstance.get(
    `/companies/${companyId}/locations`
  );
  return data;
};

​
Parameters

​
companyId
number
required
The company ID to fetch locations for

​
Multiple Companies

Retrieve locations for multiple companies at once. 
const fetchLocationsByCompanies = async (
  companyIds: number[]
): Promise<Location[]> => {
  const { data } = await axiosInstance.post('/companies/locations', {
    company_ids: companyIds,
  });
  return data;
};

​
Request Body

​
company_ids
number[]
required
Array of company IDs to fetch locations for

​
User Locations

Get locations accessible to the current user within a specific company. 
const fetchUserLocations = async (companyId: number): Promise<Location[]> => {
  const { data } = await axiosInstance.get(
    `/companies/${companyId}/user-locations`
  );
  return data;
};

​
Parameters

​
companyId
number
required
The company ID to fetch accessible locations for

​
Location Types

Common location types used in SIGEAC:

BASE

Main operational base with full facilities

HANGAR

Aircraft maintenance hangar

OFFICE

Administrative office location

WAREHOUSE

Storage and inventory facility

​
Examples

​
Get Main Base

Find the main base location for a company. 
const getMainBase = (locations: Location[]): Location | undefined => {
  return locations.find((location) => location.isMainBase);
};

​
Filter by Location Type

Get locations of a specific type. 
const getLocationsByType = (
  locations: Location[],
  type: string
): Location[] => {
  return locations.filter((location) => location.type === type);
};

// Get all hangars
const hangars = getLocationsByType(locations, 'HANGAR');

​
Check Company at Location

Check if a company operates at a specific location. 
const companyOperatesAtLocation = (
  location: Location,
  companyId: number
): boolean => {
  return location.companies.some((company) => company.id === companyId);
};

​
Get Location Display Name

Format location information for display. 
const getLocationDisplay = (location: Location): string => {
  const baseIndicator = location.isMainBase ? ' (Main Base)' : '';
  return `${location.name}${baseIndicator} - ${location.cod_iata}`;
};

// Example output: "Caracas Main Base (Main Base) - CCS"

​
Group Locations by Type

Organize locations by their type. 
const groupLocationsByType = (
  locations: Location[]
): Record<string, Location[]> => {
  return locations.reduce((acc, location) => {
    const type = location.type;
    if (!acc[type]) {
      acc[type] = [];
    }
    acc[type].push(location);
    return acc;
  }, {} as Record<string, Location[]>);
};

// Result: { BASE: [...], HANGAR: [...], WAREHOUSE: [...] }

​
Use Cases

​
Multi-location Operations

const getCompanyLocationInfo = async (companyId: number) => {
  const locations = await fetchLocationsByCompany(companyId);
  
  return {
    total: locations.length,
    mainBase: getMainBase(locations),
    byType: groupLocationsByType(locations),
    iataList: locations.map((l) => l.cod_iata),
  };
};

​
Location Selection Component

const LocationSelector = ({ companyId }: { companyId: number }) => {
  const { data: locations } = useGetLocations();
  
  const companyLocations = locations?.filter((loc) =>
    companyOperatesAtLocation(loc, companyId)
  );
  
  return (
    <select>
      {companyLocations?.map((location) => (
        <option key={location.id} value={location.id}>
          {getLocationDisplay(location)}
        </option>
      ))}
    </select>
  );
};

​
Employee Location Assignment

Locations are used in employee profiles to assign work locations: 
interface Employee {
  id: number;
  name: string;
  location: Location;
  department: Department;
}

const getEmployeesByLocation = (
  employees: Employee[],
  locationId: number
): Employee[] => {
  return employees.filter((emp) => emp.location.id === locationId);
};

​
Aircraft Location Tracking

Locations are used to track aircraft positions: 
interface Aircraft {
  id: number;
  acronym: string;
  location: Location;
}

const getAircraftAtLocation = (
  aircraft: Aircraft[],
  locationId: number
): Aircraft[] => {
  return aircraft.filter((ac) => ac.location.id === locationId);
};

​
Warehouse Integration

Locations can have associated warehouses: 
interface Warehouse {
  id: string;
  name: string;
  location: {
    address: string;
    type: string;
  };
  company: string;
  type: string;
}

const getWarehousesByLocation = async (
  locationId: number
): Promise<Warehouse[]> => {
  const { data } = await axiosInstance.get(
    `/locations/${locationId}/warehouses`
  );
  return data;
};

​
Department

Departments can be associated with locations: 
interface Department {
  id: number;
  name: string;
  address: string;
  type: string;
  cod_iata: string;
  acronym: string;
  email: string;
}

​
Employee Location

Employees are assigned to specific locations: 
const fetchEmployeesByLocation = async (
  locationId: number
): Promise<Employee[]> => {
  const { data } = await axiosInstance.get(
    `/locations/${locationId}/employees`
  );
  return data;
};

​
Error Handling

​
Common Errors

  • 401 Unauthorized: Authentication token is missing or invalid
  • 403 Forbidden: User doesn’t have access to this location
  • 404 Not Found: Location with the specified ID doesn’t exist
  • 422 Unprocessable Entity: Invalid data provided

​
Error Response

​
message
string
Error message describing the issue
​
error
string
Error type or code
{
  "message": "Location not found",
  "error": "NOT_FOUND"
}

​
Best Practices

Caching

Location data changes infrequently. Use a stale time of 5+ minutes in your queries.

Main Base

Always ensure at least one location per company is marked as the main base.

IATA Codes

Use IATA codes for display in forms and reports - they’re more recognizable to users.

Multi-company

Remember that locations can be shared between companies - always check the companies array.

Build docs developers (and LLMs) love

Get started for freeTalk to us