# Optimize

## Optimize route through waypoints

`$client->optimize->create(list<Waypoint> waypoints, ?Mode mode, ?bool roundtrip): OptimizeResult`

**post** `/api/v1/optimize`

Optimize route through waypoints

### Parameters

- `waypoints: list<Waypoint>`

  Waypoints to visit in optimized order (2-50 points)

- `mode?:optional Mode`

  Travel mode (default: `auto`)

- `roundtrip?:optional bool`

  Whether the route should return to the starting waypoint (default: true)

### Returns

- `OptimizeResult`

  - `OptimizeCompletedResult`

    - `list<Feature> features`

      Waypoints in optimized visit order

    - `string optimization`

      Optimization method used (e.g. `nearest_neighbor`, `2opt`)

    - `bool roundtrip`

      Whether the route returns to the starting waypoint

    - `float totalCostS`

      Total travel time for the optimized route in seconds

    - `Type type`

  - `OptimizeProcessingResult`

    - `string jobID`

      Job ID for polling the result

    - `Status status`

      Always `processing`

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$optimizeResult = $client->optimize->create(
  waypoints: [
    ['lat' => 48.8566, 'lng' => 2.3522],
    ['lat' => 48.8606, 'lng' => 2.3376],
    ['lat' => 48.8584, 'lng' => 2.2945],
  ],
  mode: 'auto',
  roundtrip: false,
);

var_dump($optimizeResult);
```

#### Response

```json
{
  "features": [
    {
      "geometry": {
        "coordinates": [
          2.3522,
          48.8566
        ],
        "type": "Point"
      },
      "properties": {
        "cost_s": 0,
        "cumulative_cost_s": 0,
        "waypoint_index": 0
      },
      "type": "Feature"
    }
  ],
  "optimization": "optimization",
  "roundtrip": true,
  "total_cost_s": 0,
  "type": "FeatureCollection"
}
```

## Get async optimization result

`$client->optimize->retrieve(string jobID): OptimizeJobStatus`

**get** `/api/v1/optimize/{job_id}`

Get async optimization result

### Parameters

- `jobID: string`

### Returns

- `OptimizeJobStatus`

  - `Status status`

    Current job state

  - `?OptimizeCompletedResult result`

    Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics.

### Example

```php
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(apiKey: 'My API Key', environment: 'local');

$optimizeJobStatus = $client->optimize->retrieve('job_id');

var_dump($optimizeJobStatus);
```

#### Response

```json
{
  "status": "completed",
  "result": {
    "features": [
      {
        "geometry": {
          "coordinates": [
            2.3522,
            48.8566
          ],
          "type": "Point"
        },
        "properties": {
          "cost_s": 0,
          "cumulative_cost_s": 0,
          "waypoint_index": 0
        },
        "type": "Feature"
      }
    ],
    "optimization": "optimization",
    "roundtrip": true,
    "total_cost_s": 0,
    "type": "FeatureCollection"
  }
}
```

## Domain Types

### Optimize Completed Result

- `OptimizeCompletedResult`

  - `list<Feature> features`

    Waypoints in optimized visit order

  - `string optimization`

    Optimization method used (e.g. `nearest_neighbor`, `2opt`)

  - `bool roundtrip`

    Whether the route returns to the starting waypoint

  - `float totalCostS`

    Total travel time for the optimized route in seconds

  - `Type type`

### Optimize Job Status

- `OptimizeJobStatus`

  - `Status status`

    Current job state

  - `?OptimizeCompletedResult result`

    Completed optimization result as a GeoJSON FeatureCollection. Each Feature is a waypoint in optimized visit order. Top-level fields provide summary statistics.

### Optimize Processing Result

- `OptimizeProcessingResult`

  - `string jobID`

    Job ID for polling the result

  - `Status status`

    Always `processing`

### Optimize Request

- `OptimizeRequest`

  - `list<Waypoint> waypoints`

    Waypoints to visit in optimized order (2-50 points)

  - `?Mode mode`

    Travel mode (default: `auto`)

  - `?bool roundtrip`

    Whether the route should return to the starting waypoint (default: true)

### Optimize Result

- `OptimizeResult`

  - `OptimizeCompletedResult`

    - `list<Feature> features`

      Waypoints in optimized visit order

    - `string optimization`

      Optimization method used (e.g. `nearest_neighbor`, `2opt`)

    - `bool roundtrip`

      Whether the route returns to the starting waypoint

    - `float totalCostS`

      Total travel time for the optimized route in seconds

    - `Type type`

  - `OptimizeProcessingResult`

    - `string jobID`

      Job ID for polling the result

    - `Status status`

      Always `processing`