RoutePlannerResult

RoutePlannerResult represents a Route Optimization result returned by the Geoapify Route Planner API.

It provides:

• raw response access
• normalized result data
• agent/job/shipment plans
• unassigned agents, jobs, and shipments

Getting RoutePlannerResult with RoutePlanner

The main way to get a RoutePlannerResult is from routePlanner.plan().
It can also be created directly with the constructor when you already have API response data.

import { RoutePlanner, Agent, Job } from '@geoapify/route-planner-sdk';

const planner = new RoutePlanner({ apiKey: 'YOUR_API_KEY' });

planner
  .setMode('drive')
  .addAgent(new Agent().setId('agent-1').setStartLocation(13.38, 52.52))
  .addJob(new Job().setId('job-1').setLocation(13.39, 52.51).setDuration(300));

const result = await planner.plan(); // RoutePlannerResult
const agentPlan = result.getAgentPlan('agent-1');
const firstAgentWaypoints = agentPlan?.getWaypoints() ?? [];

Constructor

new RoutePlannerResult(
  callOptions: RoutePlannerCallOptions,
  rawData: RoutePlannerResultResponseData
)

In most cases, you do not construct it manually; it is returned by RoutePlanner.plan().

Manual construction is useful when:

• you already have a saved API response JSON and want to read/analyze it with SDK helpers
• you pass planner results between services and reconstruct objects later
• you write tests with fixture JSON instead of live API calls

Example:

const result = new RoutePlannerResult(
  { apiKey: 'YOUR_API_KEY' },
  rawApiResponse
);

Methods

Method	Signature	Purpose
getData	getData(): RoutePlannerResultData	Get normalized result data
getRaw	getRaw(): RoutePlannerResultResponseData	Get raw API response
getCallOptions	getCallOptions(): RoutePlannerCallOptions	Get call options used by result
getRoutingOptions	getRoutingOptions(): RoutingOptions	Get routing options from input
getAgentPlans	getAgentPlans(): (AgentPlan \| undefined)[]	Get all agent plans
getAgentPlan	getAgentPlan(agentIdOrIndex): AgentPlan \| undefined	Get one agent plan
getJobPlans	getJobPlans(): JobPlan[]	Get all job plans
getJobPlan	getJobPlan(jobIdOrIndex): JobPlan \| undefined	Get one job plan
getShipmentPlans	getShipmentPlans(): ShipmentPlan[]	Get all shipment plans
getShipmentPlan	getShipmentPlan(shipmentIdOrIndex): ShipmentPlan \| undefined	Get one shipment plan
getUnassignedAgents	getUnassignedAgents(): AgentData[]	Get unassigned agents
getUnassignedJobs	getUnassignedJobs(): JobData[]	Get unassigned jobs
getUnassignedShipments	getUnassignedShipments(): ShipmentData[]	Get unassigned shipments

getData()

Signature: getData(): RoutePlannerResultData

Returns normalized result data generated by the SDK converter.

const normalized = result.getData();
console.log(normalized.agents.length);

getRaw()

Signature: getRaw(): RoutePlannerResultResponseData

Returns the raw Route Planner API response object.

const raw = result.getRaw();
console.log(raw.type); // e.g. "FeatureCollection"

getCallOptions()

Signature: getCallOptions(): RoutePlannerCallOptions

Returns RoutePlannerCallOptions that were used to build this result.

const callOptions = result.getCallOptions();
console.log(callOptions.apiKey);

getRoutingOptions()

Signature: getRoutingOptions(): RoutingOptions

Returns RoutingOptions from the original planner input.

const routingOptions = result.getRoutingOptions();
console.log(routingOptions.mode);

getAgentPlans()

Signature: getAgentPlans(): (AgentPlan | undefined)[]

Returns all AgentPlan objects.
The array maps 1:1 to agents from the original request (inputData.agents) by index.
Unassigned agents appear as undefined in their corresponding positions.

const agentPlans = result.getAgentPlans();
const assignedCount = agentPlans.filter(Boolean).length;

getAgentPlan()

Signature: getAgentPlan(agentIdOrIndex: string | number): AgentPlan | undefined

Returns one AgentPlan by agent ID or index.

const agentPlan = result.getAgentPlan("agent-1");
const waypoints = agentPlan?.getWaypoints() ?? [];

getJobPlans()

Signature: getJobPlans(): JobPlan[]

Returns all JobPlan objects, mapped 1:1 to input jobs by index.
Unlike getAgentPlans(), this array does not contain undefined entries. For an unassigned job, the JobPlan exists but has no agent link (getAgentPlan() / getAgentId() / getAgentIndex() return undefined).

const jobPlans = result.getJobPlans();
console.log(jobPlans.length);

const someJobPlan = jobPlans[0];
console.log(someJobPlan.getAgentPlan()); // undefined if unassigned

getJobPlan()

Signature: getJobPlan(jobIdOrIndex: string | number): JobPlan | undefined

Returns one JobPlan by job ID or index.
Returns undefined only when the requested job ID/index is not found in input.

const jobPlan = result.getJobPlan("job-42");
console.log(jobPlan?.getAgentPlan());

getShipmentPlans()

Signature: getShipmentPlans(): ShipmentPlan[]

Returns all ShipmentPlan objects, mapped 1:1 to input shipments by index.
For an unassigned shipment, the ShipmentPlan still exists but has no agent link.

const shipmentPlans = result.getShipmentPlans();
console.log(shipmentPlans.length);

const someShipmentPlan = shipmentPlans[0];
console.log(someShipmentPlan.getAgentPlan()); // undefined if unassigned

getShipmentPlan()

Signature: getShipmentPlan(shipmentIdOrIndex: string | number): ShipmentPlan | undefined

Returns one ShipmentPlan by shipment ID or index.
Returns undefined only when the requested shipment ID/index is not found in input.

const shipmentPlan = result.getShipmentPlan("order-1001");
console.log(shipmentPlan?.getAgentPlan()); // undefined if unassigned

getUnassignedAgents()

Signature: getUnassignedAgents(): AgentData[]

Returns input agent objects that are unassigned in the result.

const unassignedAgents = result.getUnassignedAgents();
console.log(unassignedAgents.length);

getUnassignedJobs()

Signature: getUnassignedJobs(): JobData[]

Returns input jobs that were not assigned to any agent.

const unassignedJobs = result.getUnassignedJobs();
console.log(unassignedJobs.map((job) => job.id));

getUnassignedShipments()

Signature: getUnassignedShipments(): ShipmentData[]

Returns input shipments that were not assigned to any agent.

const unassignedShipments = result.getUnassignedShipments();
console.log(unassignedShipments.map((shipment) => shipment.id));

RoutePlannerResultResponseData Interface

This is the original plain data object shape used in API payloads (request/response), not the SDK wrapper class.

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?: RoutePlannerIssues;
  };
  features: FeatureResponseData[];
}

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

interface AgentPlanData {
  agent_index: number;
  agent_id: string;
  time: number;
  start_time: number;
  end_time: number;
  distance: number;
  mode: string;
  legs: RouteLegData[];
  actions: RouteActionData[];
  waypoints: WaypointData[];
}

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

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

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

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

interface RoutePlannerIssues {
  unassigned_agents?: number[];
  unassigned_jobs?: number[];
  unassigned_shipments?: number[];
}

Travel and route type values are documented in RoutePlanner.

Referenced interfaces:

• AgentData
• JobData
• ShipmentData
• LocationData
• AvoidData
• FeatureResponseData
• AgentPlanData

Learn More

• RoutePlanner
• AgentPlan
• RoutePlannerResultEditor