# Optimize

## Optimize route through waypoints

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

Optimize route through waypoints

### Body Parameters

- `waypoints: GeoJsonGeometry`

  Waypoints to visit (GeoJSON MultiPoint geometry, minimum 2 points)

  - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

    GeoJSON coordinates array (nesting depth varies by geometry type)

    - `array of number`

    - `array of array of number`

    - `array of array of array of number`

    - `array of array of array of array of number`

  - `type: "Point" or "LineString" or "Polygon" or 3 more`

    - `"Point"`

    - `"LineString"`

    - `"Polygon"`

    - `"MultiPoint"`

    - `"MultiLineString"`

    - `"MultiPolygon"`

- `mode: optional "auto" or "foot" or "bicycle"`

  Travel mode (default: auto)

  - `"auto"`

  - `"foot"`

  - `"bicycle"`

- `roundtrip: optional boolean`

  Whether route returns to start (default: true)

### Returns

- `OptimizeResult = OptimizeCompletedResult or OptimizeProcessingResult`

  Optimization response — either a completed GeoJSON Feature route or an async job reference

  - `OptimizeCompletedResult = object { geometry, properties, status, type }`

    Completed optimization — GeoJSON Feature with optimized route

    - `geometry: GeoJsonGeometry`

      - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

        GeoJSON coordinates array (nesting depth varies by geometry type)

        - `array of number`

        - `array of array of number`

        - `array of array of array of number`

        - `array of array of array of array of number`

      - `type: "Point" or "LineString" or "Polygon" or 3 more`

        - `"Point"`

        - `"LineString"`

        - `"Polygon"`

        - `"MultiPoint"`

        - `"MultiLineString"`

        - `"MultiPolygon"`

    - `properties: object { distance, duration, waypoint_order }`

      - `distance: optional number`

        Total distance in meters

      - `duration: optional number`

        Estimated duration in seconds

      - `waypoint_order: optional array of number`

        Optimized waypoint ordering

    - `status: "completed"`

      Job status

      - `"completed"`

    - `type: "Feature"`

      - `"Feature"`

  - `OptimizeProcessingResult = object { job_id, status }`

    Async optimization in progress — poll with the job_id

    - `job_id: string`

      Job ID for polling

    - `status: "processing"`

      Job status

      - `"processing"`

### Example

```http
curl https://plaza.fyi/api/v1/optimize \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $PLAZA_API_KEY" \
    -d '{
          "waypoints": {
            "coordinates": [
              0
            ],
            "type": "Point"
          }
        }'
```

## Get async optimization result

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

Get async optimization result

### Path Parameters

- `job_id: string`

### Returns

- `OptimizeJobStatus = object { status, error, result }`

  Status of an async optimization job

  - `status: "completed" or "processing" or "failed"`

    Job status

    - `"completed"`

    - `"processing"`

    - `"failed"`

  - `error: optional string`

    Error message when failed

  - `result: optional unknown`

    Optimization result when completed

### Example

```http
curl https://plaza.fyi/api/v1/optimize/$JOB_ID \
    -H "Authorization: Bearer $PLAZA_API_KEY"
```

#### Response

```json
{
  "status": "completed",
  "error": "error",
  "result": {}
}
```

## Domain Types

### Optimize Completed Result

- `OptimizeCompletedResult = object { geometry, properties, status, type }`

  Completed optimization — GeoJSON Feature with optimized route

  - `geometry: GeoJsonGeometry`

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      GeoJSON coordinates array (nesting depth varies by geometry type)

      - `array of number`

      - `array of array of number`

      - `array of array of array of number`

      - `array of array of array of array of number`

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `properties: object { distance, duration, waypoint_order }`

    - `distance: optional number`

      Total distance in meters

    - `duration: optional number`

      Estimated duration in seconds

    - `waypoint_order: optional array of number`

      Optimized waypoint ordering

  - `status: "completed"`

    Job status

    - `"completed"`

  - `type: "Feature"`

    - `"Feature"`

### Optimize Job Status

- `OptimizeJobStatus = object { status, error, result }`

  Status of an async optimization job

  - `status: "completed" or "processing" or "failed"`

    Job status

    - `"completed"`

    - `"processing"`

    - `"failed"`

  - `error: optional string`

    Error message when failed

  - `result: optional unknown`

    Optimization result when completed

### Optimize Processing Result

- `OptimizeProcessingResult = object { job_id, status }`

  Async optimization in progress — poll with the job_id

  - `job_id: string`

    Job ID for polling

  - `status: "processing"`

    Job status

    - `"processing"`

### Optimize Request

- `OptimizeRequest = object { waypoints, mode, roundtrip }`

  Route optimization request through waypoints

  - `waypoints: GeoJsonGeometry`

    Waypoints to visit (GeoJSON MultiPoint geometry, minimum 2 points)

    - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

      GeoJSON coordinates array (nesting depth varies by geometry type)

      - `array of number`

      - `array of array of number`

      - `array of array of array of number`

      - `array of array of array of array of number`

    - `type: "Point" or "LineString" or "Polygon" or 3 more`

      - `"Point"`

      - `"LineString"`

      - `"Polygon"`

      - `"MultiPoint"`

      - `"MultiLineString"`

      - `"MultiPolygon"`

  - `mode: optional "auto" or "foot" or "bicycle"`

    Travel mode (default: auto)

    - `"auto"`

    - `"foot"`

    - `"bicycle"`

  - `roundtrip: optional boolean`

    Whether route returns to start (default: true)

### Optimize Result

- `OptimizeResult = OptimizeCompletedResult or OptimizeProcessingResult`

  Optimization response — either a completed GeoJSON Feature route or an async job reference

  - `OptimizeCompletedResult = object { geometry, properties, status, type }`

    Completed optimization — GeoJSON Feature with optimized route

    - `geometry: GeoJsonGeometry`

      - `coordinates: array of number or array of array of number or array of array of array of number or array of array of array of array of number`

        GeoJSON coordinates array (nesting depth varies by geometry type)

        - `array of number`

        - `array of array of number`

        - `array of array of array of number`

        - `array of array of array of array of number`

      - `type: "Point" or "LineString" or "Polygon" or 3 more`

        - `"Point"`

        - `"LineString"`

        - `"Polygon"`

        - `"MultiPoint"`

        - `"MultiLineString"`

        - `"MultiPolygon"`

    - `properties: object { distance, duration, waypoint_order }`

      - `distance: optional number`

        Total distance in meters

      - `duration: optional number`

        Estimated duration in seconds

      - `waypoint_order: optional array of number`

        Optimized waypoint ordering

    - `status: "completed"`

      Job status

      - `"completed"`

    - `type: "Feature"`

      - `"Feature"`

  - `OptimizeProcessingResult = object { job_id, status }`

    Async optimization in progress — poll with the job_id

    - `job_id: string`

      Job ID for polling

    - `status: "processing"`

      Job status

      - `"processing"`