# Optimize

## Optimize route through waypoints

`optimize.create(**kwargs) -> OptimizeResult`

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

Optimize route through waypoints

### Parameters

- `waypoints: Array[{ lat, lng}]`

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

  - `lat: Float`

    Latitude in decimal degrees (-90 to 90)

  - `lng: Float`

    Longitude in decimal degrees (-180 to 180)

- `mode: :auto | :foot | :bicycle`

  Travel mode (default: `auto`)

  - `:auto`

  - `:foot`

  - `:bicycle`

- `roundtrip: bool`

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

### Returns

- `OptimizeResult = OptimizeCompletedResult | OptimizeProcessingResult`

  Optimization response — either a completed FeatureCollection with the optimized route, or an async job reference to poll.

  - `class OptimizeCompletedResult`

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

    - `features: Array[{ geometry, properties, type}]`

      Waypoints in optimized visit order

      - `geometry: GeoJsonGeometry`

        GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

        - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

          Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

          - `Array[Float]`

            [longitude, latitude] or [longitude, latitude, elevation]

          - `Array[Array[Float]]`

            Array of [lng, lat] positions

          - `Array[Array[Array[Float]]]`

            Array of linear rings / line strings

          - `Array[Array[Array[Array[Float]]]]`

            Array of polygons

        - `type: :Point | :LineString | :Polygon | 3 more`

          Geometry type

          - `:Point`

          - `:LineString`

          - `:Polygon`

          - `:MultiPoint`

          - `:MultiLineString`

          - `:MultiPolygon`

      - `properties: { cost_s, cumulative_cost_s, waypoint_index}`

        - `cost_s: Float`

          Travel time in seconds from the previous waypoint to this one (0 for the first waypoint)

        - `cumulative_cost_s: Float`

          Cumulative travel time in seconds from the start to this waypoint

        - `waypoint_index: Integer`

          Position of this waypoint in the optimized visit order (0-based)

      - `type: :Feature`

        - `:Feature`

    - `optimization: String`

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

    - `roundtrip: bool`

      Whether the route returns to the starting waypoint

    - `total_cost_s: Float`

      Total travel time for the optimized route in seconds

    - `type: :FeatureCollection`

      - `:FeatureCollection`

  - `class OptimizeProcessingResult`

    Async optimization in progress. Poll `GET /api/v1/optimize/{job_id}` until the status changes to `completed` or `failed`.

    - `job_id: String`

      Job ID for polling the result

    - `status: :processing`

      Always `processing`

      - `:processing`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

optimize_result = plaza.optimize.create(
  waypoints: [{lat: 48.8566, lng: 2.3522}, {lat: 48.8606, lng: 2.3376}, {lat: 48.8584, lng: 2.2945}]
)

puts(optimize_result)
```

#### 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

`optimize.retrieve(job_id) -> OptimizeJobStatus`

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

Get async optimization result

### Parameters

- `job_id: String`

### Returns

- `class OptimizeJobStatus`

  Status of an async optimization job. When `completed`, the `result` field contains the full OptimizeCompletedResult. When `processing`, the job is still running — poll again. Failed jobs return a standard Error response (HTTP 422), not this schema.

  - `status: :completed | :processing`

    Current job state

    - `:completed`

    - `:processing`

  - `result: OptimizeCompletedResult`

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

    - `features: Array[{ geometry, properties, type}]`

      Waypoints in optimized visit order

      - `geometry: GeoJsonGeometry`

        GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

        - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

          Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

          - `Array[Float]`

            [longitude, latitude] or [longitude, latitude, elevation]

          - `Array[Array[Float]]`

            Array of [lng, lat] positions

          - `Array[Array[Array[Float]]]`

            Array of linear rings / line strings

          - `Array[Array[Array[Array[Float]]]]`

            Array of polygons

        - `type: :Point | :LineString | :Polygon | 3 more`

          Geometry type

          - `:Point`

          - `:LineString`

          - `:Polygon`

          - `:MultiPoint`

          - `:MultiLineString`

          - `:MultiPolygon`

      - `properties: { cost_s, cumulative_cost_s, waypoint_index}`

        - `cost_s: Float`

          Travel time in seconds from the previous waypoint to this one (0 for the first waypoint)

        - `cumulative_cost_s: Float`

          Cumulative travel time in seconds from the start to this waypoint

        - `waypoint_index: Integer`

          Position of this waypoint in the optimized visit order (0-based)

      - `type: :Feature`

        - `:Feature`

    - `optimization: String`

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

    - `roundtrip: bool`

      Whether the route returns to the starting waypoint

    - `total_cost_s: Float`

      Total travel time for the optimized route in seconds

    - `type: :FeatureCollection`

      - `:FeatureCollection`

### Example

```ruby
require "plaza"

plaza = Plaza::Client.new(
  api_key: "My API Key",
  environment: "local" # defaults to "production"
)

optimize_job_status = plaza.optimize.retrieve("job_id")

puts(optimize_job_status)
```

#### 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

- `class OptimizeCompletedResult`

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

  - `features: Array[{ geometry, properties, type}]`

    Waypoints in optimized visit order

    - `geometry: GeoJsonGeometry`

      GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

      - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

        Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

        - `Array[Float]`

          [longitude, latitude] or [longitude, latitude, elevation]

        - `Array[Array[Float]]`

          Array of [lng, lat] positions

        - `Array[Array[Array[Float]]]`

          Array of linear rings / line strings

        - `Array[Array[Array[Array[Float]]]]`

          Array of polygons

      - `type: :Point | :LineString | :Polygon | 3 more`

        Geometry type

        - `:Point`

        - `:LineString`

        - `:Polygon`

        - `:MultiPoint`

        - `:MultiLineString`

        - `:MultiPolygon`

    - `properties: { cost_s, cumulative_cost_s, waypoint_index}`

      - `cost_s: Float`

        Travel time in seconds from the previous waypoint to this one (0 for the first waypoint)

      - `cumulative_cost_s: Float`

        Cumulative travel time in seconds from the start to this waypoint

      - `waypoint_index: Integer`

        Position of this waypoint in the optimized visit order (0-based)

    - `type: :Feature`

      - `:Feature`

  - `optimization: String`

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

  - `roundtrip: bool`

    Whether the route returns to the starting waypoint

  - `total_cost_s: Float`

    Total travel time for the optimized route in seconds

  - `type: :FeatureCollection`

    - `:FeatureCollection`

### Optimize Job Status

- `class OptimizeJobStatus`

  Status of an async optimization job. When `completed`, the `result` field contains the full OptimizeCompletedResult. When `processing`, the job is still running — poll again. Failed jobs return a standard Error response (HTTP 422), not this schema.

  - `status: :completed | :processing`

    Current job state

    - `:completed`

    - `:processing`

  - `result: OptimizeCompletedResult`

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

    - `features: Array[{ geometry, properties, type}]`

      Waypoints in optimized visit order

      - `geometry: GeoJsonGeometry`

        GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

        - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

          Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

          - `Array[Float]`

            [longitude, latitude] or [longitude, latitude, elevation]

          - `Array[Array[Float]]`

            Array of [lng, lat] positions

          - `Array[Array[Array[Float]]]`

            Array of linear rings / line strings

          - `Array[Array[Array[Array[Float]]]]`

            Array of polygons

        - `type: :Point | :LineString | :Polygon | 3 more`

          Geometry type

          - `:Point`

          - `:LineString`

          - `:Polygon`

          - `:MultiPoint`

          - `:MultiLineString`

          - `:MultiPolygon`

      - `properties: { cost_s, cumulative_cost_s, waypoint_index}`

        - `cost_s: Float`

          Travel time in seconds from the previous waypoint to this one (0 for the first waypoint)

        - `cumulative_cost_s: Float`

          Cumulative travel time in seconds from the start to this waypoint

        - `waypoint_index: Integer`

          Position of this waypoint in the optimized visit order (0-based)

      - `type: :Feature`

        - `:Feature`

    - `optimization: String`

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

    - `roundtrip: bool`

      Whether the route returns to the starting waypoint

    - `total_cost_s: Float`

      Total travel time for the optimized route in seconds

    - `type: :FeatureCollection`

      - `:FeatureCollection`

### Optimize Processing Result

- `class OptimizeProcessingResult`

  Async optimization in progress. Poll `GET /api/v1/optimize/{job_id}` until the status changes to `completed` or `failed`.

  - `job_id: String`

    Job ID for polling the result

  - `status: :processing`

    Always `processing`

    - `:processing`

### Optimize Request

- `class OptimizeRequest`

  Route optimization (Travelling Salesman) request. Finds the most efficient order to visit a set of waypoints. Minimum 2 waypoints, maximum 50. For large inputs, the request may be processed asynchronously.

  - `waypoints: Array[{ lat, lng}]`

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

    - `lat: Float`

      Latitude in decimal degrees (-90 to 90)

    - `lng: Float`

      Longitude in decimal degrees (-180 to 180)

  - `mode: :auto | :foot | :bicycle`

    Travel mode (default: `auto`)

    - `:auto`

    - `:foot`

    - `:bicycle`

  - `roundtrip: bool`

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

### Optimize Result

- `OptimizeResult = OptimizeCompletedResult | OptimizeProcessingResult`

  Optimization response — either a completed FeatureCollection with the optimized route, or an async job reference to poll.

  - `class OptimizeCompletedResult`

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

    - `features: Array[{ geometry, properties, type}]`

      Waypoints in optimized visit order

      - `geometry: GeoJsonGeometry`

        GeoJSON Geometry object per RFC 7946. Coordinates use [longitude, latitude] order. 3D coordinates [lng, lat, elevation] are used for elevation endpoints.

        - `coordinates: Array[Float] | Array[Array[Float]] | Array[Array[Array[Float]]] | Array[Array[Array[Array[Float]]]]`

          Coordinates array. Nesting depth varies by geometry type: Point = [lng, lat], LineString = [[lng, lat], ...], Polygon = [[[lng, lat], ...], ...], etc.

          - `Array[Float]`

            [longitude, latitude] or [longitude, latitude, elevation]

          - `Array[Array[Float]]`

            Array of [lng, lat] positions

          - `Array[Array[Array[Float]]]`

            Array of linear rings / line strings

          - `Array[Array[Array[Array[Float]]]]`

            Array of polygons

        - `type: :Point | :LineString | :Polygon | 3 more`

          Geometry type

          - `:Point`

          - `:LineString`

          - `:Polygon`

          - `:MultiPoint`

          - `:MultiLineString`

          - `:MultiPolygon`

      - `properties: { cost_s, cumulative_cost_s, waypoint_index}`

        - `cost_s: Float`

          Travel time in seconds from the previous waypoint to this one (0 for the first waypoint)

        - `cumulative_cost_s: Float`

          Cumulative travel time in seconds from the start to this waypoint

        - `waypoint_index: Integer`

          Position of this waypoint in the optimized visit order (0-based)

      - `type: :Feature`

        - `:Feature`

    - `optimization: String`

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

    - `roundtrip: bool`

      Whether the route returns to the starting waypoint

    - `total_cost_s: Float`

      Total travel time for the optimized route in seconds

    - `type: :FeatureCollection`

      - `:FeatureCollection`

  - `class OptimizeProcessingResult`

    Async optimization in progress. Poll `GET /api/v1/optimize/{job_id}` until the status changes to `completed` or `failed`.

    - `job_id: String`

      Job ID for polling the result

    - `status: :processing`

      Always `processing`

      - `:processing`