### Get Depots and Create Plan (Node.js with Axios)

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-plan-with-depot

This example shows how to fetch depots and create a plan using the Axios library in Node.js.

```APIDOC
## GET /public/v0.2b/depots

### Description
Retrieves a list of existing depots.

### Method
GET

### Endpoint
https://api.getcircuit.com/public/v0.2b/depots

### Parameters
#### Auth
- **username** (string) - Required - API key for Basic Authentication.

### Request Example
```javascript
const axios = require('axios')
const apiKey = '<your-api-key>'

axios.get('https://api.getcircuit.com/public/v0.2b/depots', {
  auth: {
    username: apiKey
  }
})
```

### Response
#### Success Response (200)
- **depots** (array) - A list of depot objects, each containing 'id' and 'name'.
- **nextPageToken** (string | null) - Token for pagination.

#### Response Example
```json
{
  "depots": [
    {
      "id": "depots/abcd1234",
      "name": "something"
    }
  ],
  "nextPageToken": null
}
```

## POST /public/v0.2b/plans

### Description
Creates a new plan for a specified depot.

### Method
POST

### Endpoint
https://api.getcircuit.com/public/v0.2b/plans

### Parameters
#### Auth
- **username** (string) - Required - API key for Basic Authentication.

#### Request Body
- **title** (string) - Required - The title of the plan.
- **starts** (object) - Required - The start date of the plan.
  - **day** (integer) - Required - The day of the month.
  - **month** (integer) - Required - The month of the year.
  - **year** (integer) - Required - The year.
- **depot** (string) - Required - The ID of the depot for which the plan is created.

### Request Example
```javascript
const axios = require('axios')
const apiKey = '<your-api-key>'
const depotId = 'depots/abcd1234' // Example depot ID
const planData = {
  title: 'Test',
  starts: {
    day: 31,
    month: 5,
    year: 2023
  },
  depot: depotId
}

axios.post('https://api.getcircuit.com/public/v0.2b/plans', planData, {
  auth: {
    username: apiKey
  }
})
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created plan.
- **title** (string) - The title of the plan.
- **starts** (object) - The start date of the plan.
  - **day** (integer) - The day of the month.
  - **month** (integer) - The month of the year.
  - **year** (integer) - The year.
- **depot** (string) - The ID of the depot associated with the plan.

#### Response Example
```json
{
  "id": "plans/FQ95Ex714KYeojkeIm77",
  "title": "Test",
  "starts": {
    "day": 31,
    "month": 5,
    "year": 2023
  },
  "depot": "depots/abcd1234"
}
```
```

--------------------------------

### GET /public/v0.2b/drivers and POST /public/v0.2b/plans (curl)

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-plan-with-drivers

This snippet provides an example of how to use curl to first list drivers and then create a plan.

```APIDOC
## GET /public/v0.2b/drivers

### Description
Retrieves a list of available drivers.

### Method
GET

### Endpoint
/public/v0.2b/drivers

### Parameters
#### Headers
- **Authorization** (string) - Required - Basic authentication with API key.

### Request Example
```bash
curl -X GET \
  'https://api.getcircuit.com/public/v0.2b/drivers' \
  -H 'Authorization: Basic <your-api-key-base64-encoded>'
```

### Response
#### Success Response (200)
- **drivers** (array) - A list of driver objects, each containing an 'id'.
- **nextPageToken** (string) - Token for pagination, null if no more pages.

#### Response Example
```json
{
  "drivers": [
    {
      "id": "drivers/abcd1234",
      "name": "Driver Name",
      "email": "driver@example.com"
    }
  ],
  "nextPageToken": null
}
```

## POST /public/v0.2b/plans

### Description
Creates a new plan with specified drivers.

### Method
POST

### Endpoint
/public/v0.2b/plans

### Parameters
#### Headers
- **Authorization** (string) - Required - Basic authentication with API key.
- **Content-Type** (string) - Required - application/json

#### Request Body
- **title** (string) - Required - The title of the plan.
- **starts** (object) - Required - The start date of the plan.
  - **day** (integer) - Required - Day of the month.
  - **month** (integer) - Required - Month of the year.
  - **year** (integer) - Required - Year.
- **drivers** (array) - Required - A list of driver IDs to include in the plan.

### Request Example
```bash
curl -X POST \
  'https://api.getcircuit.com/public/v0.2b/plans' \
  -H 'Authorization: Basic <your-api-key-base64-encoded>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Test Plan",
    "starts": {
      "day": 31,
      "month": 5,
      "year": 2023
    },
    "drivers": ["drivers/abcd1234"]
  }'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created plan.
- **title** (string) - The title of the plan.
- **starts** (object) - The start date of the plan.
- **drivers** (array) - A list of driver objects included in the plan.

#### Response Example
```json
{
  "id": "plans/FQ95Ex714KYeojkeIm77",
  "title": "Test Plan",
  "starts": {
    "day": 31,
    "month": 5,
    "year": 2023
  },
  "drivers": [
    {
      "id": "drivers/abcd1234",
      "name": "Driver Name"
    }
  ]
}
```
```

--------------------------------

### Get Depots and Create Plan (JavaScript)

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-plan-with-depot

This example demonstrates how to retrieve a list of depots and then create a plan for one of them using JavaScript's Fetch API.

```APIDOC
## GET /public/v0.2b/depots

### Description
Retrieves a list of existing depots.

### Method
GET

### Endpoint
https://api.getcircuit.com/public/v0.2b/depots

### Parameters
#### Headers
- **Authorization** (string) - Required - Basic authentication with API key.

### Request Example
```javascript
const apiKey = '<your-api-key>'
const headers = new Headers()
headers.append('Authorization', `Basic ${btoa(`${apiKey}:`)}`)

fetch('https://api.getcircuit.com/public/v0.2b/depots', {
  method: 'GET',
  headers: headers
})
```

### Response
#### Success Response (200)
- **depots** (array) - A list of depot objects, each containing 'id' and 'name'.
- **nextPageToken** (string | null) - Token for pagination.

#### Response Example
```json
{
  "depots": [
    {
      "id": "depots/abcd1234",
      "name": "something"
    }
  ],
  "nextPageToken": null
}
```

## POST /public/v0.2b/plans

### Description
Creates a new plan for a specified depot.

### Method
POST

### Endpoint
https://api.getcircuit.com/public/v0.2b/plans

### Parameters
#### Headers
- **Authorization** (string) - Required - Basic authentication with API key.
- **Content-Type** (string) - Required - application/json

#### Request Body
- **title** (string) - Required - The title of the plan.
- **starts** (object) - Required - The start date of the plan.
  - **day** (integer) - Required - The day of the month.
  - **month** (integer) - Required - The month of the year.
  - **year** (integer) - Required - The year.
- **depot** (string) - Required - The ID of the depot for which the plan is created.

### Request Example
```javascript
const apiKey = '<your-api-key>'
const depotId = 'depots/abcd1234' // Example depot ID
const planData = {
  title: 'Test',
  starts: {
    day: 31,
    month: 5,
    year: 2023
  },
  depot: depotId
}
const headersPost = new Headers()
headersPost.append('Authorization', `Basic ${btoa(`${apiKey}:`)}`)
headersPost.append('Content-Type', 'application/json')

fetch('https://api.getcircuit.com/public/v0.2b/plans', {
  method: 'POST',
  headers: headersPost,
  body: JSON.stringify(planData)
})
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created plan.
- **title** (string) - The title of the plan.
- **starts** (object) - The start date of the plan.
  - **day** (integer) - The day of the month.
  - **month** (integer) - The month of the year.
  - **year** (integer) - The year.
- **depot** (string) - The ID of the depot associated with the plan.

#### Response Example
```json
{
  "id": "plans/FQ95Ex714KYeojkeIm77",
  "title": "Test",
  "starts": {
    "day": 31,
    "month": 5,
    "year": 2023
  },
  "depot": "depots/abcd1234"
}
```
```

--------------------------------

### Get Depots and Create Plan (Python)

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-plan-with-depot

This example illustrates how to use the 'requests' library in Python to interact with the API for fetching depots and creating plans.

```APIDOC
## GET /public/v0.2b/depots

### Description
Retrieves a list of existing depots.

### Method
GET

### Endpoint
https://api.getcircuit.com/public/v0.2b/depots

### Parameters
#### Auth
- **username** (string) - Required - API key for HTTP Basic Authentication.

### Request Example
```python
import requests
from requests.auth import HTTPBasicAuth

apiKey = "<your-api-key>"

response = requests.get(
    "https://api.getcircuit.com/public/v0.2b/depots", auth=HTTPBasicAuth(apiKey, "")
)
```

### Response
#### Success Response (200)
- **depots** (list) - A list of depot objects, each containing 'id' and 'name'.
- **nextPageToken** (str or None) - Token for pagination.

#### Response Example
```json
{
  "depots": [
    {
      "id": "depots/abcd1234",
      "name": "something"
    }
  ],
  "nextPageToken": null
}
```

## POST /public/v0.2b/plans

### Description
Creates a new plan for a specified depot.

### Method
POST

### Endpoint
https://api.getcircuit.com/public/v0.2b/plans

### Parameters
#### Auth
- **username** (string) - Required - API key for HTTP Basic Authentication.

#### Request Body
- **title** (str) - Required - The title of the plan.
- **starts** (dict) - Required - The start date of the plan.
  - **day** (int) - Required - The day of the month.
  - **month** (int) - Required - The month of the year.
  - **year** (int) - Required - The year.
- **depot** (str) - Required - The ID of the depot for which the plan is created.

### Request Example
```python
import requests
from requests.auth import HTTPBasicAuth

apiKey = "<your-api-key>"
depotId = "depots/abcd1234"  # Example depot ID
planData = {
    "title": "Test",
    "starts": {"day": 31, "month": 5, "year": 2023},
    "depot": depotId,
}

response = requests.post(
    "https://api.getcircuit.com/public/v0.2b/plans",
    json=planData,
    auth=HTTPBasicAuth(apiKey, ""),
)
```

### Response
#### Success Response (200)
- **id** (str) - The unique identifier of the created plan.
- **title** (str) - The title of the plan.
- **starts** (dict) - The start date of the plan.
  - **day** (int) - The day of the month.
  - **month** (int) - The month of the year.
  - **year** (int) - The year.
- **depot** (str) - The ID of the depot associated with the plan.

#### Response Example
```json
{
  "id": "plans/FQ95Ex714KYeojkeIm77",
  "title": "Test",
  "starts": {
    "day": 31,
    "month": 5,
    "year": 2023
  },
  "depot": "depots/abcd1234"
}
```
```

--------------------------------

### Create Plan for Depot using curl API

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-plan-with-depot

This example demonstrates how to create a plan for a depot using the curl command-line tool. It first retrieves a list of depots using a GET request and then uses the ID of the first depot to create a new plan via a POST request. Basic authentication is used with the API key.

```bash
# First, get the depot ID
API_KEY="<your-api-key>"
DEPOT_ID=$(curl -s -u "$API_KEY:" "https://api.getcircuit.com/public/v0.2b/depots" | jq -r '.depots[0].id')

# Now, create the plan using the depot ID
curl -s -X POST "https://api.getcircuit.com/public/v0.2b/plans" \
     -u "$API_KEY:" \
     -H "Content-Type: application/json" \
     -d "{\"title\": \"Test Plan\", \"starts\": {\"day\": 31, \"month\": 5, \"year\": 2023}, \"depot\": \"$DEPOT_ID\"}"
```

--------------------------------

### GET /public/v0.2b/drivers

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-plan-with-drivers

Retrieves a list of existing drivers.

```APIDOC
## GET /public/v0.2b/drivers

### Description
Retrieves a list of existing drivers.

### Method
GET

### Endpoint
https://api.getcircuit.com/public/v0.2b/drivers

### Parameters
#### Path Parameters
None

#### Query Parameters
- **nextPageToken** (string) - Optional - Token for retrieving the next page of results.

### Request Example
```bash
curl https://api.getcircuit.com/public/v0.2b/drivers -u <your-api-key>:
```

### Response
#### Success Response (200)
- **drivers** (array of objects) - A list of drivers.
  - **id** (string) - The unique identifier for the driver.
- **nextPageToken** (string) - Token for retrieving the next page of results, or null if there are no more pages.

#### Response Example
```json
{
  "drivers": [
    {
      "id": "drivers/abcd1234"
    }
  ],
  "nextPageToken": null
}
```
```

--------------------------------

### GET /public/v0.2b/drivers and POST /public/v0.2b/plans (JavaScript Web)

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-plan-with-drivers

This snippet demonstrates how to first retrieve a list of drivers using the GET /drivers endpoint and then create a plan with a selected driver using the POST /plans endpoint in JavaScript for web applications.

```APIDOC
## GET /public/v0.2b/drivers

### Description
Retrieves a list of available drivers.

### Method
GET

### Endpoint
/public/v0.2b/drivers

### Parameters
#### Headers
- **Authorization** (string) - Required - Basic authentication with API key.

### Request Example
```javascript
const apiKey = '<your-api-key>'
const headers = new Headers()
headers.append('Authorization', `Basic ${btoa(`${apiKey}:`)}`)

fetch('https://api.getcircuit.com/public/v0.2b/drivers', {
  method: 'GET',
  headers: headers
})
```

### Response
#### Success Response (200)
- **drivers** (array) - A list of driver objects, each containing an 'id'.
- **nextPageToken** (string) - Token for pagination, null if no more pages.

#### Response Example
```json
{
  "drivers": [
    {
      "id": "drivers/abcd1234",
      "name": "Driver Name",
      "email": "driver@example.com"
    }
  ],
  "nextPageToken": null
}
```

## POST /public/v0.2b/plans

### Description
Creates a new plan with specified drivers.

### Method
POST

### Endpoint
/public/v0.2b/plans

### Parameters
#### Headers
- **Authorization** (string) - Required - Basic authentication with API key.
- **Content-Type** (string) - Required - application/json

#### Request Body
- **title** (string) - Required - The title of the plan.
- **starts** (object) - Required - The start date of the plan.
  - **day** (integer) - Required - Day of the month.
  - **month** (integer) - Required - Month of the year.
  - **year** (integer) - Required - Year.
- **drivers** (array) - Required - A list of driver IDs to include in the plan.

### Request Example
```javascript
const planData = {
  title: 'Test Plan',
  starts: {
    day: 31,
    month: 5,
    year: 2023
  },
  drivers: ['drivers/abcd1234']
}

const headersPost = new Headers(headers)
headersPost.append('Content-Type', 'application/json')

fetch('https://api.getcircuit.com/public/v0.2b/plans', {
  method: 'POST',
  headers: headersPost,
  body: JSON.stringify(planData)
})
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created plan.
- **title** (string) - The title of the plan.
- **starts** (object) - The start date of the plan.
- **drivers** (array) - A list of driver objects included in the plan.

#### Response Example
```json
{
  "id": "plans/FQ95Ex714KYeojkeIm77",
  "title": "Test Plan",
  "starts": {
    "day": 31,
    "month": 5,
    "year": 2023
  },
  "drivers": [
    {
      "id": "drivers/abcd1234",
      "name": "Driver Name"
    }
  ]
}
```
```

--------------------------------

### Date Object Example - JSON

Source: https://developer.dispatch.spoke.com/docs/models/plan

This JSON object represents a specific date, including the year, month, and day. It is used to define the start date of a plan.

```json
{
  "year": 2023,
  "month": 2,
  "day": 1
}
```

--------------------------------

### Create Plan and Import Stops with curl

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-import-plan-stops

This example demonstrates how to create a delivery plan and import stops using the curl command-line tool. It shows the necessary headers, including authentication with an API key, and the JSON payloads for creating a plan and importing stops.

```bash
# Replace <your-api-key> with your actual API key
API_KEY="<your-api-key>"

# Create a plan
PLAN_RESPONSE=$(curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n $API_KEY | base64):" \
  --data '{ "title": "Test Plan", "starts": { "day": 31, "month": 5, "year": 2023 } }' \
  https://api.getcircuit.com/public/v0.2b/plans)

# Extract the plan ID (assuming the response is JSON and contains an 'id' field)
PLAN_ID=$(echo $PLAN_RESPONSE | jq -r '.id')

# If plan creation was successful, import stops
if [ -n "$PLAN_ID" ]; then
  echo "Plan created with ID: $PLAN_ID"
  STOP_IMPORT_RESPONSE=$(curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Basic $(echo -n $API_KEY | base64):" \
    --data '[ { "address": { "addressLineOne": "Some valid address" } }, { "address": { "addressLineOne": "Some other valid address" } } ]' \
    "https://api.getcircuit.com/public/v0.2b/$PLAN_ID/stops:import")
  echo "Stop import response:"
  echo $STOP_IMPORT_RESPONSE
else
  echo "Failed to create plan."
  echo "Response: $PLAN_RESPONSE"
fi

```

--------------------------------

### Time of Day Object Example

Source: https://developer.dispatch.spoke.com/docs/models/driver

Illustrates the TimeOfDay object structure, used to represent a specific time with hour and minute components. This is utilized for setting driver start and end times.

```json
{
  "hour": 8,
  "minute": 0
}
```

--------------------------------

### PlanOptimizationOperationMetadata Example (JSON)

Source: https://developer.dispatch.spoke.com/docs/models/operation

This JSON object contains metadata associated with a plan optimization operation. It includes timestamps for when the operation started and finished, whether it was canceled, the target plan ID, and who initiated the operation.

```json
{
  "startedAt": 1631100800,
  "finishedAt": 1631101600,
  "canceled": false,
  "targetPlanId": "plans/zeOCJaJCzZhpKVCVAC9o",
  "startedBy": "api"
}
```

--------------------------------

### Create Plan and Import Stops using cURL

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-import-plan-stops

This section provides cURL commands to interact with the Circuit API. It demonstrates how to create a delivery plan and then import stops into that plan using command-line requests. Authentication is handled using basic authentication with an API key. It also shows how to retrieve details for a specific stop.

```bash
# First create a plan for a specific day. Here we create one named "Test" for
# the day 2023-05-31. Do not include the <> signs in the api key
curl https://api.getcircuit.com/public/v0.2b/plans \
   -d '{"title": "Test", "starts": {"day":31, "month": 5, "year": 2023}}' \
   -H 'Content-Type: application/json' \
   -u <your-api-key>:

# This will return a response similar to the following:
# {
#   "id": "plans/FQ95Ex714KYeojkeIm77",
#   "title": "Test",
#   "starts": {
#     "day": 31,
#     "month": 5,
#     "year": 2023
#   },
#   "depot": null,
#   "distributed": false,
#   "writable": true,
#   "optimization": "creating",
#   "drivers": [],
#   "routes": []
# }

# Now, with the returned ID, you can add stops to this plan (notice the plan id
# in the url):
curl https://api.getcircuit.com/public/v0.2b/plans/FQ95Ex714KYeojkeIm77/stops:import \
   -d'[
        {
          "address": {
            "addressLineOne": "Some address"
          }
        },
        {
          "address": {
            "addressLineOne": "Some other address"
          }
        }
      ]' \
   -H 'Content-Type: application/json' \
   -u <your-api-key>:

# With proper addresses the above requests will return a response similar to the
# following:
# {
#   "success": [
#     "plans/FQ95Ex714KYeojkeIm77/stops/vgsTiQi85ueWRs1JnXx7",
#     "plans/FQ95Ex714KYeojkeIm77/stops/q0HUM8SwBPt8n3pYZOeO"
#   ],
#   "failed": []
# }

# If you wish to retrieve more information about one of the create stops you can
# issue a GET request for it:
curl https://api.getcircuit.com/public/v0.2b/plans/FQ95Ex714KYeojkeIm77/stops/vgsTiQi85ueWRs1JnXx7 \
   -u <your-api-key>:

```

--------------------------------

### RouteState Object Example - JSON

Source: https://developer.dispatch.spoke.com/docs/models/route

This JSON object represents the state of a route, including completion status, distribution status, notification status, and start status, along with corresponding timestamps. Timestamps are provided in Epoch seconds.

```json
{
  "completed": false,
  "completedAt": null,
  "distributed": true,
  "distributedAt": 1669153050,
  "notifiedRecipients": false,
  "notifiedRecipientsAt": null,
  "started": false,
  "startedAt": null
}
```

--------------------------------

### Pagination Example

Source: https://developer.dispatch.spoke.com/openapi

Demonstrates how to retrieve paginated data using the `nextPageToken` and `pageToken` query parameters.

```APIDOC
## GET /public/v0.2b/plans

### Description
Retrieves a list of plans, with support for pagination.

### Method
GET

### Endpoint
`/public/v0.2b/plans`

### Query Parameters
- **filter.startsGte** (string) - Optional - Filter plans starting on or after the specified date.
- **pageToken** (string) - Optional - Token for retrieving the next page of results.
- **maxPageSize** (integer) - Optional - Maximum number of results per page. Each endpoint has a specific maximum value.

### Request Example
```bash
curl "https://api.getcircuit.com/public/v0.2b/plans?filter.startsGte=2023-05-01" -u yourApiKey:
```

### Response
#### Success Response (200)
- **nextPageToken** (string) - Token to retrieve the next page of results. `null` if there are no more pages.

#### Response Example
```json
{
  "nextPageToken": "I53Jr5Jr5Eu2qK9omh0iA8q"
}
```

### Pagination Usage
To retrieve subsequent pages, use the `nextPageToken` from the previous response as the `pageToken` query parameter in your next request. Ensure all initial query parameters are retained.

```bash
curl "https://api.getcircuit.com/public/v0.2b/plans?filter.startsGte=2023-05-01&pageToken=I53Jr5Eu2qK9omh0iA8q" -u yourApiKey:
```
```

--------------------------------

### Route Object Example - JSON

Source: https://developer.dispatch.spoke.com/docs/models/route

This JSON object represents a Route, detailing its ID, title, stop count, current state, associated driver, and plan. The state field provides boolean flags and timestamps for completion, distribution, notification, and start.

```json
{
  "id": "routes/gjaqksJIa26qGPzsgBXT",
  "title": "Tue, Nov 22 Route 1",
  "stopCount": 28,
  "state": {
    "completed": false,
    "completedAt": null,
    "distributed": true,
    "distributedAt": 1669153050,
    "notifiedRecipients": false,
    "notifiedRecipientsAt": null,
    "started": false,
    "startedAt": null
  },
  "driver": "drivers/w8ZaNn3e5ZA8EQSABtca",
  "plan": "plans/zeOCJaJCzZhpKVCVAC9o"
}
```

--------------------------------

### Plan Object Example - JSON

Source: https://developer.dispatch.spoke.com/docs/models/plan

This JSON object demonstrates the structure of a 'Plan' in the API. It includes details like plan ID, title, start date, driver information, depot, routes, optimization state, and distribution status. The 'writable' property indicates if the plan can be edited via standard APIs.

```json
{
  "id": "plans/zeOCJaJCzZhpKVCVAC9o",
  "title": "Tue, Nov 22 Route 1",
  "starts": {
    "day": 22,
    "month": 11,
    "year": 2022
  },
  "drivers": [
    {
      "id": "drivers/w8ZaNn3e5ZA8EQSABtca",
      "name": null,
      "email": "verygooddriver@spoke.com",
      "phoneNumber": null,
      "depots": [
        "depots/zeOCJaJCzZhpKVCVAC9o"
      ],
      "routeOverrides": {
        "startTime": {
          "hour": 8,
          "minute": 0
        },
        "endTime": {
          "hour": 8,
          "minute": 0
        },
        "startAddress": {
          "address": "Very nice St., 150 - Nice Neighbourhood, Campinas - SP, 130876, Brazil",
          "placeId": "1cda3f263368264eefbb",
          "latitude": -22.12345,
          "longitude": -47.12345,
          "placeTypes": [
            "street_address"
          ],
          "addressLineOne": "Very nice St., 150",
          "addressLineTwo": "Nice Neighbourhood, Campinas - SP, 130876, Brazil"
        },
        "endAddress": {
          "address": "Very nice St., 150 - Nice Neighbourhood, Campinas - SP, 130876, Brazil",
          "placeId": "1cda3f263368264eefbb",
          "latitude": -22.12345,
          "longitude": -47.12345,
          "placeTypes": [
            "street_address"
          ],
          "addressLineOne": "Very nice St., 150",
          "addressLineTwo": "Nice Neighbourhood, Campinas - SP, 130876, Brazil"
        },
        "maxStops": 30,
        "drivingSpeed": "average",
        "deliverySpeed": "faster"
      }
    }
  ],
  "routes": [
    "routes/gjaqksJIa26qGPzsgBXT"
  ],
  "depot": "depots/zeOCJaJCzZhpKVCVAC9o",
  "optimization": 'optimized',
  "distributed": true,
  "writable": false
}
```

--------------------------------

### GET /public/v0.2b/drivers and POST /public/v0.2b/plans (Node.js)

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-plan-with-drivers

This snippet shows how to fetch a list of drivers and then create a plan using those drivers in a Node.js environment using the axios library.

```APIDOC
## GET /public/v0.2b/drivers

### Description
Retrieves a list of available drivers.

### Method
GET

### Endpoint
/public/v0.2b/drivers

### Parameters
#### Auth
- **username** (string) - Required - Your API key.

### Request Example
```javascript
const axios = require('axios')
const apiKey = '<your-api-key>'

axios.get('https://api.getcircuit.com/public/v0.2b/drivers', {
  auth: {
    username: apiKey
  }
})
```

### Response
#### Success Response (200)
- **drivers** (array) - A list of driver objects, each containing an 'id'.
- **nextPageToken** (string) - Token for pagination, null if no more pages.

#### Response Example
```json
{
  "drivers": [
    {
      "id": "drivers/abcd1234",
      "name": "Driver Name",
      "email": "driver@example.com"
    }
  ],
  "nextPageToken": null
}
```

## POST /public/v0.2b/plans

### Description
Creates a new plan with specified drivers.

### Method
POST

### Endpoint
/public/v0.2b/plans

### Parameters
#### Auth
- **username** (string) - Required - Your API key.

#### Request Body
- **title** (string) - Required - The title of the plan.
- **starts** (object) - Required - The start date of the plan.
  - **day** (integer) - Required - Day of the month.
  - **month** (integer) - Required - Month of the year.
  - **year** (integer) - Required - Year.
- **drivers** (array) - Required - A list of driver IDs to include in the plan.

### Request Example
```javascript
const planData = {
  title: 'Test Plan',
  starts: {
    day: 31,
    month: 5,
    year: 2023
  },
  drivers: ['drivers/abcd1234']
}

axios.post('https://api.getcircuit.com/public/v0.2b/plans', planData, {
  auth: {
    username: apiKey
  }
})
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created plan.
- **title** (string) - The title of the plan.
- **starts** (object) - The start date of the plan.
- **drivers** (array) - A list of driver objects included in the plan.

#### Response Example
```json
{
  "id": "plans/FQ95Ex714KYeojkeIm77",
  "title": "Test Plan",
  "starts": {
    "day": 31,
    "month": 5,
    "year": 2023
  },
  "drivers": [
    {
      "id": "drivers/abcd1234",
      "name": "Driver Name"
    }
  ]
}
```
```

--------------------------------

### Create Plan with Driver using curl

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-plan-with-drivers

This curl command demonstrates how to create a plan with a driver. It first retrieves a list of drivers using a GET request and then uses the ID of the first driver in a POST request to create the plan. Authentication is handled via Basic Auth with an API key. The output shows the JSON response for the created plan.

```bash
# First, get the driver ID
API_KEY="<your-api-key>"
DRIVER_ID=$(curl -s -u "$API_KEY:" "https://api.getcircuit.com/public/v0.2b/drivers" | jq -r '.drivers[0].id')

# Then, create the plan with the driver ID
curl -s -X POST "https://api.getcircuit.com/public/v0.2b/plans" \
     -u "$API_KEY:" \
     -H "Content-Type: application/json" \
     -d "{\"title\": \"Test\", \"starts\": {\"day\": 31, \"month\": 5, \"year\": 2023}, \"drivers\": [\"$DRIVER_ID\"]}"
```

--------------------------------

### Start Address Object

Source: https://developer.dispatch.spoke.com/openapi

Defines the structure for the starting address of a route, including optional geocoding overrides.

```APIDOC
## Start Address Object

### Description
Address of a start location for every route assigned to this driver. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.

### Properties
This object inherits all properties from the general Address Object, with the addition of the `addressName` field's specific usage note.

### Nullable
- The start address object can be `nullable: true`.
```

--------------------------------

### POST /public/v0.2b/plans

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-plan-with-drivers

Creates a new plan with specified details including title, start date, and associated drivers.

```APIDOC
## POST /public/v0.2b/plans

### Description
Creates a new plan with specified details including title, start date, and associated drivers.

### Method
POST

### Endpoint
https://api.getcircuit.com/public/v0.2b/plans

### Parameters
#### Query Parameters
None

#### Request Body
- **title** (string) - Required - The title of the plan.
- **starts** (object) - Required - The start date of the plan.
  - **day** (integer) - Required - The day of the month.
  - **month** (integer) - Required - The month of the year.
  - **year** (integer) - Required - The year.
- **drivers** (array of strings) - Required - A list of driver IDs to associate with the plan.

### Request Example
```json
{
  "title": "Test",
  "starts": {
    "day": 31,
    "month": 5,
    "year": 2023
  },
  "drivers": ["drivers/abcd1234"]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created plan.
- **title** (string) - The title of the plan.
- **starts** (object) - The start date of the plan.
  - **day** (integer) - The day of the month.
  - **month** (integer) - The month of the year.
  - **year** (integer) - The year.
- **drivers** (array of objects) - A list of drivers associated with the plan.
  - **id** (string) - The unique identifier for the driver.

#### Response Example
```json
{
  "id": "plans/FQ95Ex714KYeojkeIm77",
  "title": "Test",
  "starts": {
    "day": 31,
    "month": 5,
    "year": 2023
  },
  "drivers": [
    {
      "id": "drivers/abcd1234"
    }
  ]
}
```
```

--------------------------------

### Optimize, Check, and Distribute Plan using cURL

Source: https://developer.dispatch.spoke.com/docs/api-examples/optimize-distribute-plan

This set of cURL commands demonstrates how to interact with the Circuit API for plan optimization and distribution. It includes initiating optimization, polling for operation status, and finally distributing the plan. Replace `<your-api-key>` with your actual API key and `plans/KBoYtDxO3FMh7zJkWdU3` with your plan ID.

```bash
# Optimize the plan
curl https://api.getcircuit.com/public/v0.2b/plans/KBoYtDxO3FMh7zJkWdU3:optimize \
   -X POST \
   -u <your-api-key>:

# Check operation status (replace FQ95Ex714KYeojkeIm77 with the operation ID from the previous step)
curl https://api.getcircuit.com/public/v0.2b/operations/FQ95Ex714KYeojkeIm77 \
   -u <your-api-key>:

# Distribute the optimized plan
curl https://api.getcircuit.com/public/v0.2b/plans/KBoYtDxO3FMh7zJkWdU3:distribute \
   -X POST \
   -u <your-api-key>:

```

--------------------------------

### Get Operation Status

Source: https://developer.dispatch.spoke.com/docs/api-examples/create-and-delete-stops-from-live-plan

Retrieves the status of an asynchronous operation. This is a GET request to the /operations/{operationId} endpoint.

```APIDOC
## GET /public/v0.2b/operations/{operationId}

### Description
Retrieves the status of an asynchronous operation. This endpoint should be polled periodically until the `done` field is `true`.

### Method
GET

### Endpoint
/public/v0.2b/operations/{operationId}

### Parameters
#### Path Parameters
- **operationId** (string) - Required - The ID of the operation to check.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **operation** (object) - The status of the operation.
  - **id** (string) - The ID of the operation.
  - **done** (boolean) - Indicates if the operation is complete.
  - **type** (string) - The type of operation.
  - **result** (object) - The result of the operation. Contains `code` and `message` if an error occurred, or fields like `skipped_stops` and `optimized_stops` on success.

#### Response Example
```json
{
  "id": "operations/FQ95Ex714KYeojkeIm77",
  "done": true,
  "type": "plan_optimization",
  "result": {
    "skipped_stops": 0,
    "optimized_stops": 5
  }
}
```
```

--------------------------------

### Initialize API Request (Python with requests)

Source: https://developer.dispatch.spoke.com/docs/api-examples/update-stops-from-live-plan

This Python code snippet shows the initialization of API requests using the 'requests' library. It sets up basic authentication with an API key. This is a foundational step for making subsequent API calls.

```python
# We are using the requests library here to make requests from Python
import requests
from requests.auth import HTTPBasicAuth
import time
```

--------------------------------

### Depot Object Example

Source: https://developer.dispatch.spoke.com/docs/models/depot

This is an example of the Depot object, which represents depot data in the API. It includes a unique identifier and a name.

```json
{
 "id": "depots/zeOCJaJCzZhpKVCVAC9o",
 "name": "Depot 1"
}
```

--------------------------------

### Driver Dispatch Information

Source: https://developer.dispatch.spoke.com/openapi

This section details the structure for driver dispatch information, including start and end times, and start and end addresses.

```APIDOC
## POST /websites/developer_dispatch_spoke

### Description
This endpoint allows for the creation or update of driver dispatch information, including scheduling and location details.

### Method
POST

### Endpoint
/websites/developer_dispatch_spoke

### Parameters
#### Request Body
- **driverEndTime** (object) - Required - The driver's end time for the dispatch. It includes hour and minute.
  - **hour** (integer) - Required - Hour of the day (0-23).
  - **minute** (integer) - Required - Minute of the hour (0-59).
- **startAddress** (object) - Required - The driver's starting location.
  - **address** (string) - Required - The full address of the stop.
  - **addressLineOne** (string) - Required - The first line of the address.
  - **addressLineTwo** (string) - Optional - The second line of the address.
  - **latitude** (number) - Required - The latitude of the address in decimal degrees (-90 to 90).
  - **longitude** (number) - Required - The longitude of the address in decimal degrees (-180 to 180).
  - **placeId** (string) - Required - The identifier of the place corresponding to this stop on Google Places.
  - **placeTypes** (array of strings) - Required - Array of strings provided by the Google AutoCompleteAPI.
- **endAddress** (object) - Required - The driver's ending location.
  - **address** (string) - Required - The full address of the stop.
  - **addressLineOne** (string) - Required - The first line of the address.
  - **addressLineTwo** (string) - Optional - The second line of the address.
  - **latitude** (number) - Required - The latitude of the address in decimal degrees (-90 to 90).
  - **longitude** (number) - Required - The longitude of the address in decimal degrees (-180 to 180).
  - **placeId** (string) - Required - The identifier of the place corresponding to this stop on Google Places.
  - **placeTypes** (array of strings) - Required - Array of strings provided by the Google AutoCompleteAPI.

### Request Example
```json
{
  "driverEndTime": {
    "hour": 17,
    "minute": 30
  },
  "startAddress": {
    "address": "123 Main St, Anytown, CA 90210",
    "addressLineOne": "123 Main St",
    "addressLineTwo": null,
    "latitude": 34.0522,
    "longitude": -118.2437,
    "placeId": "ChIJN1t_t6tEwoARr_7_j5_p7_8",
    "placeTypes": ["route", "geocode"]
  },
  "endAddress": {
    "address": "456 Oak Ave, Anytown, CA 90210",
    "addressLineOne": "456 Oak Ave",
    "addressLineTwo": null,
    "latitude": 34.0523,
    "longitude": -118.2438,
    "placeId": "ChIJN1t_t6tEwoARr_7_j5_p7_9",
    "placeTypes": ["route", "geocode"]
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the dispatch information was updated successfully.

#### Response Example
```json
{
  "message": "Driver dispatch information updated successfully."
}
```
```