@geoapify/route-planner-sdk/dist/index.d.ts

TypeScript SDK for the Geoapify Route Planner API. Supports route optimization, delivery planning, and timeline visualization in browser and Node.js

type TravelMode = "drive" | "light_truck" | "medium_truck" | "truck" | "heavy_truck" | "truck_dangerous_goods" | "long_truck" | "bus" | "scooter" | "motorcycle" | "bicycle" | "mountain_bike" | "road_bike" | "walk" | "hike" | "transit" | "approximated_transit";

type AvoidType = "tolls" | "tolls:importance" | "ferries" | "ferries:importance" | "highways" | "highways:importance" | "locations" | "location" | "location_lonlat";

type TrafficType = "free_flow" | "approximated";

type DistanceUnitType = "metric" | "imperial";

type RouteType = "balanced" | "short" | "less_maneuvers";

interface BreakData {
    duration?: number;
    time_windows: [number, number][];
}

interface AgentData {
    start_location?: [number, number];
    start_location_index?: number;
    end_location?: [number, number];
    end_location_index?: number;
    pickup_capacity?: number;
    delivery_capacity?: number;
    capabilities: string[];
    time_windows: [number, number][];
    breaks: BreakData[];
    id?: string;
    description?: string;
}

interface CoordinatesData {
    lon?: number;
    lat?: number;
}

interface AvoidData {
    type?: AvoidType;
    values: CoordinatesData[];
}

interface JobData {
    location?: [number, number];
    location_index?: number;
    priority?: number;
    duration?: number;
    pickup_amount?: number;
    delivery_amount?: number;
    requirements: string[];
    time_windows: [number, number][];
    id?: string;
    description?: string;
}

interface LocationData {
    id?: string;
    location?: [number, number];
}

interface ShipmentStepData {
    location?: [number, number];
    location_index?: number;
    duration?: number;
    time_windows: [number, number][];
}

interface ShipmentData {
    id?: string;
    pickup?: ShipmentStepData;
    delivery?: ShipmentStepData;
    requirements: string[];
    priority?: number;
    description?: string;
    amount?: number;
}

interface RoutePlannerInputData {
    mode?: TravelMode;
    agents: AgentData[];
    jobs: JobData[];
    shipments: ShipmentData[];
    locations: LocationData[];
    avoid: AvoidData[];
    traffic?: TrafficType;
    type?: RouteType;
    max_speed?: number;
    units?: DistanceUnitType;
}

interface GeometryResponseData {
    type: string;
    coordinates: [number, number][];
}

interface LegStepResponseData {
    distance: number;
    time: number;
    from_index: number;
    to_index: number;
}

interface LegResponseData {
    distance: number;
    time: number;
    steps: LegStepResponseData[];
    from_waypoint_index: number;
    to_waypoint_index: number;
}

interface ActionResponseData {
    type: string;
    start_time: number;
    duration: number;
    shipment_index?: number;
    shipment_id?: string;
    location_index?: number;
    location_id?: string;
    job_index?: number;
    job_id?: string;
    index?: number;
    waypoint_index?: number;
}

interface WaypointResponseData {
    original_location: [number, number];
    original_location_index?: number;
    original_location_id?: number;
    location: [number, number];
    start_time: number;
    duration: number;
    actions: ActionResponseData[];
    prev_leg_index?: number;
    next_leg_index?: number;
}

interface PropertiesResponseData {
    agent_index: number;
    agent_id: string;
    time: number;
    start_time: number;
    end_time: number;
    distance: number;
    mode: string;
    legs?: LegResponseData[];
    actions: ActionResponseData[];
    waypoints: WaypointResponseData[];
}

interface FeatureResponseData {
    geometry: GeometryResponseData;
    type: string;
    properties: PropertiesResponseData;
}

interface RoutePlannerResultResponseData {
    type: string;
    properties: {
        mode: string;
        params: {
            mode?: TravelMode;
            agents: AgentData[];
            jobs: JobData[];
            shipments: ShipmentData[];
            locations: LocationData[];
            avoid: AvoidData[];
            traffic?: TrafficType;
            type?: RouteType;
            max_speed?: number;
            units?: DistanceUnitType;
        };
        issues: {
            unassigned_agents: number[];
            unassigned_jobs: number[];
            unassigned_shipments: number[];
        };
    };
    features: FeatureResponseData[];
}

interface RouteActionData {
    type: string;
    start_time: number;
    duration: number;
    shipment_index?: number;
    shipment_id?: string;
    location_index?: number;
    location_id?: string;
    job_index?: number;
    job_id?: string;
    index?: number;
    waypoint_index?: number;
}

interface WaypointData {
    original_location: [number, number];
    original_location_index?: number;
    original_location_id?: number;
    location: [number, number];
    start_time: number;
    duration: number;
    actions: RouteActionData[];
    prev_leg_index?: number;
    next_leg_index?: number;
}

interface RouteLegStepData {
    distance: number;
    time: number;
    from_index: number;
    to_index: number;
}

interface RouteLegData {
    time: number;
    distance: number;
    steps: RouteLegStepData[];
    from_waypoint_index: number;
    to_waypoint_index: number;
}

interface AgentSolutionData {
    agentIndex: number;
    agentId: string;
    time: number;
    start_time: number;
    end_time: number;
    distance: number;
    mode: string;
    legs: RouteLegData[];
    actions: RouteActionData[];
    waypoints: WaypointData[];
}

interface RoutePlannerResultData {
    agents: AgentSolutionData[];
    inputData: RoutePlannerInputData;
    unassignedAgents: number[];
    unassignedJobs: number[];
    unassignedShipments: number[];
}

declare class Break {
    private raw;
    constructor(raw?: BreakData);
    getRaw(): BreakData;
    setRaw(value: BreakData): this;
    addTimeWindow(start: number, end: number): this;
    setDuration(duration: number): this;
}

declare class Agent {
    private raw;
    constructor(raw?: AgentData);
    getRaw(): AgentData;
    setRaw(value: AgentData): this;
    setStartLocation(lon: number, lat: number): this;
    setStartLocationIndex(value: number): this;
    setEndLocation(lon: number, lat: number): this;
    setEndLocationIndex(value: number): this;
    setPickupCapacity(value: number): this;
    setDeliveryCapacity(value: number): this;
    addCapability(value: string): this;
    addTimeWindow(start: number, end: number): this;
    addBreak(value: Break): this;
    setId(value: string): this;
    setDescription(value: string): this;
}

declare class Avoid {
    private raw;
    constructor(raw?: AvoidData);
    getRaw(): AvoidData;
    setRaw(value: AvoidData): this;
    setType(type: AvoidType): this;
    addValue(lon: number, lat: number): this;
}

declare class Coordinates {
    private raw;
    constructor(raw?: CoordinatesData);
    getRaw(): CoordinatesData;
    setRaw(value: CoordinatesData): this;
    setLat(lat: number): this;
    setLon(lon: number): this;
}

declare class Job {
    private raw;
    constructor(raw?: JobData);
    getRaw(): JobData;
    setRaw(value: JobData): this;
    setLocation(lon: number, lat: number): this;
    setLocationIndex(value: number): this;
    setPriority(value: number): this;
    setDuration(value: number): this;
    setPickupAmount(value: number): this;
    setDeliveryAmount(value: number): this;
    addRequirement(value: string): this;
    addTimeWindow(start: number, end: number): this;
    setId(value: string): this;
    setDescription(value: string): this;
}

declare class Location {
    private raw;
    constructor(raw?: LocationData);
    getRaw(): LocationData;
    setRaw(value: LocationData): this;
    setId(id: string): this;
    setLocation(lon: number, lat: number): this;
}

declare class ShipmentStep {
    private raw;
    constructor(raw?: ShipmentStepData);
    getRaw(): ShipmentStepData;
    setRaw(value: ShipmentStepData): this;
    setLocation(lon: number, lat: number): this;
    setLocationIndex(value: number): this;
    setDuration(value: number): this;
    addTimeWindow(start: number, end: number): this;
}

declare class Shipment {
    private raw;
    constructor(raw?: ShipmentData);
    getRaw(): ShipmentData;
    setRaw(value: ShipmentData): this;
    setId(id: string): this;
    setPickup(value: ShipmentStep): this;
    setDelivery(value: ShipmentStep): this;
    addRequirement(value: string): this;
    setPriority(value: number): this;
    setDescription(value: string): this;
    setAmount(value: number): this;
}

declare class RouteLegStep {
    private readonly raw;
    constructor(raw?: RouteLegStepData);
    getRaw(): RouteLegStepData;
    getDistance(): number;
    getTime(): number;
    getFromIndex(): number;
    getToIndex(): number;
}

declare class RouteLeg {
    private readonly raw;
    constructor(raw?: RouteLegData);
    getRaw(): RouteLegData;
    getTime(): number;
    getDistance(): number;
    getSteps(): RouteLegStep[];
    getFromWaypointIndex(): number;
    getToWaypointIndex(): number;
}

declare class RouteAction {
    private readonly raw;
    constructor(raw?: RouteActionData);
    getRaw(): RouteActionData;
    getType(): string;
    getStartTime(): number;
    getDuration(): number;
    getShipmentIndex(): number | undefined;
    getShipmentId(): string | undefined;
    getLocationIndex(): number | undefined;
    getLocationId(): string | undefined;
    getJobIndex(): number | undefined;
    getJobId(): string | undefined;
    getIndex(): number | undefined;
    getWaypointIndex(): number | undefined;
}

declare class Waypoint {
    private readonly raw;
    constructor(raw?: WaypointData);
    getRaw(): WaypointData;
    getOriginalLocation(): [number, number];
    getOriginalLocationIndex(): number | undefined;
    getOriginalLocationId(): number | undefined;
    getLocation(): [number, number];
    getStartTime(): number;
    getDuration(): number;
    getActions(): RouteAction[];
    getPrevLegIndex(): number | undefined;
    getNextLegIndex(): number | undefined;
}

declare class AgentSolution {
    private readonly raw;
    constructor(raw?: AgentSolutionData);
    getRaw(): AgentSolutionData;
    getAgentIndex(): number;
    getAgentId(): string;
    getTime(): number;
    getStartTime(): number;
    getEndTime(): number;
    getDistance(): number;
    getMode(): string;
    getLegs(): RouteLeg[];
    getActions(): RouteAction[];
    getWaypoints(): Waypoint[];
}

declare class RouteActionInfo {
    private readonly raw;
    constructor(raw?: RouteActionInfoData);
    getRaw(): RouteActionInfoData;
    getAgentId(): string;
    getActions(): RouteAction[];
    getAgent(): AgentSolution;
}

declare class RoutePlannerError extends Error {
    errorName: string;
    message: string;
    rawResponse: any;
    constructor(errorName: string, message: string, rawResponse: any);
}

interface RoutePlannerOptions {
    apiKey: string;
    baseUrl?: string;
    httpOptions?: Record<string, any>;
}

interface JobSolutionData {
    agentId: string;
    actions: RouteActionData[];
    agent: AgentSolutionData;
    job: JobData;
}

declare class JobSolution {
    private readonly raw;
    constructor(raw?: JobSolutionData);
    getRaw(): JobSolutionData;
    getAgentId(): string;
    getActions(): RouteAction[];
    getAgent(): AgentSolution;
    getJob(): Job;
}

interface ShipmentSolutionData {
    agentId: string;
    actions: RouteActionData[];
    agent: AgentSolutionData;
    shipment: ShipmentData;
}

declare class ShipmentSolution {
    private readonly raw;
    constructor(raw?: ShipmentSolutionData);
    getRaw(): ShipmentSolutionData;
    getAgentId(): string;
    getActions(): RouteAction[];
    getAgent(): AgentSolution;
    getShipment(): Shipment;
}

type RouteDetailsType = "instruction_details" | "route_details" | "elevation";

interface RoutingOptions {
    mode: TravelMode;
    type?: RouteType;
    units?: DistanceUnitType;
    lang?: string;
    avoid?: AvoidType[];
    details?: RouteDetailsType[];
    traffic?: TrafficType;
    max_speed?: number;
}

/**
 * Provides convenient methods for reading Route Planner API results.
 */
declare class RoutePlannerResult {
    private readonly rawData;
    private readonly options;
    constructor(options: RoutePlannerOptions, rawData: RoutePlannerResultResponseData);
    /**
     * Returns the data returned by the Route Planner API.
     */
    getData(): RoutePlannerResultData;
    /**
     * Returns the raw data returned by the Route Planner API.
     */
    getRawData(): RoutePlannerResultResponseData;
    /**
     * Returns a list of all assigned agent solutions.
     */
    getAgentSolutions(): AgentSolution[];
    /**
     * Returns a list of all agent solutions by index. (if it's not assigned, then it will be undefined)
     */
    getAgentSolutionsByIndex(): (AgentSolution | undefined)[];
    /**
     * Finds an agent's solution by their ID.
     */
    getAgentSolution(agentId: string): AgentSolution | undefined;
    /**
     * Finds an agent's solution by their index.
     */
    getAgentSolutionByIndex(agentIndex: number): AgentSolution | undefined;
    /**
     * Retrieves all waypoints of a specific agent.
     */
    getAgentWaypoints(agentId: string): Waypoint[];
    /**
     * Retrieves all route actions of a specific agent.
     */
    getAgentRouteActions(agentId: string): RouteAction[];
    /**
     * Retrieves all route legs of a specific agent.
     */
    getAgentRouteLegs(agentId: string): RouteLeg[];
    /**
     * Retrieves the options used to generate the result.
     */
    getOptions(): RoutePlannerOptions;
    /**
    * Retrieves all jobs assigned to a specific agent.
    */
    getAgentJobs(agentId: string): number[];
    /**
     * Retrieves all shipments assigned to a specific agent.
     */
    getAgentShipments(agentId: string): number[];
    /**
     * Retrieves unassigned agents.
     */
    getUnassignedAgents(): AgentData[];
    /**
     * Retrieves unassigned jobs.
     */
    getUnassignedJobs(): JobData[];
    /**
     * Retrieves unassigned shipments.
     */
    getUnassignedShipments(): ShipmentData[];
    /**
     * Returns a list of all assigned jobs
     */
    getJobSolutions(): JobSolution[];
    /**
     * Finds job solution by their ID.
     */
    getJobSolution(jobId: string): JobSolution | undefined;
    /**
     * Returns a list of all assigned shipments
     */
    getShipmentSolutions(): ShipmentSolution[];
    /**
     * Finds shipment solution by their ID.
     */
    getShipmentSolution(jobId: string): ShipmentSolution | undefined;
    /**
     * Retrieves detailed information about a specific job.
     */
    getJobInfo(jobId: string): RouteActionInfo | undefined;
    /**
     * Retrieves detailed information about a specific shipment.
     */
    getShipmentInfo(shipmentId: string): RouteActionInfo | undefined;
    /**
     * Retrieves detailed information about a specific job.
     */
    getJobInfoByIndex(jobIndex: number): RouteActionInfo | undefined;
    /**
     * Retrieves detailed information about a specific shipment.
     */
    getShipmentInfoByIndex(shipmentIndex: number): RouteActionInfo | undefined;
    /**
     * Retrieves the route for a specific agent.
     * @param agentId - The ID of the agent.
     * @param options - The routing options.
     */
    getAgentRoute(agentId: string, options: RoutingOptions): Promise<any | undefined>;
    private constructRoutingRequest;
}

interface RouteActionInfoData {
    agentId: string;
    actions: RouteAction[];
    agent: AgentSolution;
}

interface RoutePlannerTimelineLabel {
    position: string;
    label: string;
}

interface TimelineItem {
    position: string;
    actualWidth: string;
    minWidth: string;
    form: 'full' | 'standard' | 'minimal';
    type: 'start' | 'job' | 'end';
    description: string;
}

interface Timeline {
    label: string;
    mode?: TravelMode;
    color: string;
    description: string;
    routeVisible: boolean;
    agentIndex: number;
    timelineLength: string;
    distanceLineLength: string;
    timelineLeft: string;
    itemsByTime: TimelineItem[];
    itemsByDistance: TimelineItem[];
}

interface TimelineMenuItem {
    key: string;
    label: string;
    callback: (agentIndex: number) => void;
}

interface RoutePlannerTimelineOptions {
    timelineType?: 'time' | 'distance';
    hasLargeDescription?: boolean;
    capacityUnit?: string;
    agentLabel?: string;
    label?: string;
    description?: string;
    timeLabels?: RoutePlannerTimelineLabel[];
    distanceLabels?: RoutePlannerTimelineLabel[];
    agentColors?: string[];
    showWaypointPopup?: boolean;
    waypointPopupGenerator?: (waypoint: Waypoint) => HTMLElement;
    agentMenuItems?: TimelineMenuItem[];
}

declare class RoutePlanner {
    private raw;
    private options;
    constructor(options: RoutePlannerOptions, raw?: RoutePlannerInputData);
    getRaw(): RoutePlannerInputData;
    setRaw(value: RoutePlannerInputData): this;
    setMode(mode: TravelMode): this;
    addAgent(agent: Agent): this;
    addJob(job: Job): this;
    addLocation(location: Location): this;
    addShipment(shipment: Shipment): this;
    addAvoid(avoid: Avoid): this;
    setTraffic(traffic: TrafficType): this;
    setType(type: RouteType): this;
    setMaxSpeed(max_speed: number): this;
    setUnits(units: DistanceUnitType): this;
    plan(): Promise<RoutePlannerResult>;
}

declare class RoutePlannerResultEditor {
    private readonly result;
    constructor(result: RoutePlannerResult);
    /**
     * Assigns a job to an agent. Removes the job if it's currently assigned to another agent
     * @param agentIdOrIndex - The index/id of the agent.
     * @param jobIndexesOrIds - Indexes/ids of the jobs.
     * @param newPriority - The new priority of the job.
     * @returns {boolean} - Returns true if the job was successfully assigned.
     */
    assignJobs(agentIdOrIndex: string | number, jobIndexesOrIds: number[] | string[], newPriority?: number): Promise<boolean>;
    /**
     * Assigns a shipment to an agent. Removes the shipment if it's currently assigned to another agent
     * @param shipmentIndexesOrIds - The indexes/ids of the shipments.
     * @param agentIdOrIndex - The index/id of the agent.
     * @param newPriority - The new priority of the shipment.
     * @returns {boolean} - Returns true if the shipment was successfully assigned.
     */
    assignShipments(agentIdOrIndex: string | number, shipmentIndexesOrIds: number[] | string[], newPriority?: number): Promise<boolean>;
    /**
     * Removes a job from the plan.
     * @param jobIndexesOrIds - The indexes/ids of the jobs to remove.
     * @returns {boolean} - Returns true if the job was successfully removed.
     */
    removeJobs(jobIndexesOrIds: number[] | string[]): Promise<boolean>;
    /**
     * Removes a shipment from the plan.
     * @param shipmentIndexesOrIds - The indexes/ids of the shipments to remove.
     * @returns {boolean} - Returns true if the shipment was successfully removed.
     */
    removeShipments(shipmentIndexesOrIds: number[] | string[]): Promise<boolean>;
    /**
     * Adds new jobs to an agent's schedule.
     * @param jobs - An array of job objects to be added.
     * @param agentIdOrIndex - The index/id of the agent.
     * @returns {boolean} - Returns true if jobs were successfully added.
     */
    addNewJobs(agentIdOrIndex: string | number, jobs: Job[]): Promise<boolean>;
    /**
     * Adds new shipments to an agent's schedule.
     * @param shipments - An array of shipment objects to be added.
     * @param agentIdOrIndex - The index/id of the agent.
     * @returns {boolean} - Returns true if shipments were successfully added.
     */
    addNewShipments(agentIdOrIndex: string | number, shipments: Shipment[]): Promise<boolean>;
    /**
     * Returns the modified result.
     * @returns {RoutePlannerResult} - The modified result object.
     */
    getModifiedResult(): RoutePlannerResult;
    private assertArray;
    private convertJobsToIndexes;
    private convertShipmentsToIndexes;
    private convertAgentToIndex;
}

declare class RoutePlannerTimeline {
    private readonly WAYPOINT_POPUP_INITIALIZED_ATTRIBUTE;
    private readonly WAYPOINT_POPUP_CONTAINER_ID;
    defaultColors: string[];
    timelineTemplate: (timeline: Timeline, index: number, timelineType: 'time' | 'distance', timeLabels: RoutePlannerTimelineLabel[], distanceLabels: RoutePlannerTimelineLabel[], agentMenuItems?: TimelineMenuItem[]) => string;
    container: HTMLElement;
    inputData?: RoutePlannerInputData;
    result?: RoutePlannerResult;
    options: RoutePlannerTimelineOptions;
    waypointPopupContainer: HTMLElement | null;
    eventListeners: {
        [key: string]: Function[];
    };
    constructor(container: HTMLElement, inputData?: RoutePlannerInputData, result?: RoutePlannerResult, options?: RoutePlannerTimelineOptions);
    getHasLargeDescription(): boolean | undefined;
    setHasLargeDescription(value: boolean): void;
    getTimelineType(): 'time' | 'distance' | undefined;
    setTimelineType(value: 'time' | 'distance'): void;
    getAgentColors(): string[] | undefined;
    setAgentColors(value: string[]): void;
    getCapacityUnit(): string | undefined;
    setCapacityUnit(value: string | undefined): void;
    getTimeLabels(): RoutePlannerTimelineLabel[] | undefined;
    setTimeLabels(value: RoutePlannerTimelineLabel[]): void;
    getDistanceLabels(): RoutePlannerTimelineLabel[] | undefined;
    setDistanceLabels(value: RoutePlannerTimelineLabel[]): void;
    getAgentLabel(): string | undefined;
    setAgentLabel(value: string): void;
    getAgentMenuItems(): TimelineMenuItem[] | undefined;
    setAgentMenuItems(value: TimelineMenuItem[]): void;
    getResult(): RoutePlannerResult | undefined;
    setResult(value: RoutePlannerResult): void;
    on(eventName: string, handler: Function): void;
    off(eventName: string, handler: Function): void;
    getAgentColorByIndex(index: number): string;
    private generateAgentTimeline;
    private drawTimelines;
    private generateTimelinesData;
    private emit;
    private generateItemsByTime;
    private generateItemsByDistance;
    private generateAgentDescription;
    private initializeGlobalTooltip;
    private createWaypointPopupContainer;
    private initializeWaypointPopups;
    private showWaypointPopup;
    private hideWaypointPopup;
    private initializeThreeDotMenus;
    private toggleThreeDotMenu;
    private closeAllThreeDotMenus;
}

export { type ActionResponseData, Agent, type AgentData, AgentSolution, type AgentSolutionData, Avoid, type AvoidData, type AvoidType, Break, type BreakData, Coordinates, type CoordinatesData, type DistanceUnitType, type FeatureResponseData, type GeometryResponseData, Job, type JobData, type LegResponseData, type LegStepResponseData, Location, type LocationData, type PropertiesResponseData, RouteAction, type RouteActionData, RouteActionInfo, type RouteActionInfoData, RouteLeg, type RouteLegData, RouteLegStep, type RouteLegStepData, RoutePlanner, RoutePlannerError, type RoutePlannerInputData, RoutePlannerResult, type RoutePlannerResultData, RoutePlannerResultEditor, type RoutePlannerResultResponseData, RoutePlannerTimeline, type RoutePlannerTimelineLabel, type RoutePlannerTimelineOptions, type RouteType, Shipment, type ShipmentData, ShipmentStep, type ShipmentStepData, type Timeline, type TimelineItem, type TimelineMenuItem, type TrafficType, type TravelMode, Waypoint, type WaypointData, type WaypointResponseData, RoutePlanner as default };