Creating a Plan and importing Stops

Here we will be using the Plan Create and the Stops Batch Import endpoints to create a Plan for a day and import Stops into that Plan. Read their descriptions to see all the available options.

JS Web

// Set the API key
const apiKey = '<your-api-key>'

// Headers for the request
const headers = new Headers()
headers.append('Content-Type', 'application/json')
headers.append('Authorization', `Basic ${btoa(`${apiKey}:`)}`)

async function createPlanAndAddStops() {
  // Plan details
  const planData = {
    title: 'Test',
    starts: {
      day: 31,
      month: 5,
      year: 2023,
    },
  }

  // First create a plan for a specific day. Here we create one named "Test" for
  // the day 2023-05-31.
  const planResponse = await fetch(
    'https://api.getcircuit.com/public/v0.2b/plans',
    {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(planData),
    },
  )

  // The response will return an object similar to the following:
  // {
  //   "id": "plans/FQ95Ex714KYeojkeIm77",
  //   "title": "Test",
  //   "starts": {
  //     "day": 31,
  //     "month": 5,
  //     "year": 2023
  //   },
  //   ...
  // }
  const plan = await planResponse.json()
  console.log(plan)

  // Stop details. Remember to provide valid addresses.
  const stopData = [
    {
      address: {
        addressLineOne: 'Some valid address',
      },
    },
    {
      address: {
        addressLineOne: 'Some other valid address',
      },
    },
  ]

  // Now, with the returned ID, we can add stops to this plan
  const stopsImportResponse = await fetch(
    `https://api.getcircuit.com/public/v0.2b/${plan.id}/stops:import`,
    {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(stopData),
    },
  )

  // With proper addresses the above request will return a response similar to the
  // following:
  // {
  //   "success": [
  //     "plans/FQ95Ex714KYeojkeIm77/stops/vgsTiQi85ueWRs1JnXx7",
  //     "plans/FQ95Ex714KYeojkeIm77/stops/q0HUM8SwBPt8n3pYZOeO"
  //   ],
  //   "failed": []
  // }
  const stops = await stopsImportResponse.json()
  console.log(stops)

  // If you wish to retrieve more information about one of the create stops you can
  // issue a GET request for it:
  const stopGetResponse = await fetch(
    `https://api.getcircuit.com/public/v0.2b/${stops.success[0]}`,
    {
      headers: new Headers({
        Authorization: `Basic ${btoa(`${apiKey}:`)}`,
      }),
    },
  )

  // The response will return information about the stop.
  const stopData = await stopGetResponse.json()
  console.log(stopData)
}

Node

// We are using the axios library here to make requests from Node
const axios = require('axios')

// Set the API key
const apiKey = '<your-api-key>'

async function createPlanAndAddStops() {
  // Plan details
  const planData = {
    title: 'Test',
    starts: {
      day: 31,
      month: 5,
      year: 2023,
    },
  }

  // First create a plan for a specific day. Here we create one named "Test" for
  // the day 2023-05-31.
  const planResponse = await axios.post(
    'https://api.getcircuit.com/public/v0.2b/plans',
    planData,
    {
      auth: { username: apiKey },
    },
  )

  // The response will return an object similar to the following:
  // {
  //   "id": "plans/FQ95Ex714KYeojkeIm77",
  //   "title": "Test",
  //   "starts": {
  //     "day": 31,
  //     "month": 5,
  //     "year": 2023
  //   },
  //   ...
  // }
  const plan = planResponse.data
  console.log(plan)

  // Stop details. Remember to provide valid addresses.
  const stopData = [
    {
      address: {
        addressLineOne: 'Some valid address',
      },
    },
    {
      address: {
        addressLineOne: 'Some other valid address',
      },
    },
  ]

  // Now, with the returned ID, we can add stops to this plan
  const stopsImportResponse = await axios.post(
    `https://api.getcircuit.com/public/v0.2b/${plan.id}/stops:import`,
    stopData,
    {
      auth: { username: apiKey },
    },
  )

  // With proper addresses the above request will return a response similar to the
  // following:
  // {
  //   "success": [
  //     "plans/FQ95Ex714KYeojkeIm77/stops/vgsTiQi85ueWRs1JnXx7",
  //     "plans/FQ95Ex714KYeojkeIm77/stops/q0HUM8SwBPt8n3pYZOeO"
  //   ],
  //   "failed": []
  // }
  const stops = stopsImportResponse.data
  console.log(stops)

  // If you wish to retrieve more information about one of the create stops you can
  // issue a GET request for it:
  const stopGetResponse = await axios.get(
    `https://api.getcircuit.com/public/v0.2b/${stops.success[0]}`,
    {
      auth: { username: apiKey },
    },
  )

  // The response will return information about the stop.
  const stopInfo = stopGetResponse.data
  console.log(stopInfo)
}

Python

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

# Set the API key
api_key = "<your-api-key>"

# Plan details
plan_data = {"title": "Test", "starts": {"day": 31, "month": 5, "year": 2023}}

# First create a plan for a specific day. Here we create one named "Test" for
# the day 2023-05-31.
plan_response = requests.post(
    "https://api.getcircuit.com/public/v0.2b/plans",
    auth=HTTPBasicAuth(api_key, ""),
    json=plan_data,
)

# The response will return an object similar to the following:
# {
#   "id": "plans/FQ95Ex714KYeojkeIm77",
#   "title": "Test",
#   "starts": {
#     "day": 31,
#     "month": 5,
#     "year": 2023
#   },
#   ...
# }
plan = plan_response.json()
print(plan)

# Stop details. Remember to provide valid addresses.
stop_data = [
    {"address": {"addressLineOne": "Some valid address"}},
    {"address": {"addressLineOne": "Some other valid address"}},
]

# Now, with the returned ID, we can add stops to this plan
stops_import_response = requests.post(
    f'https://api.getcircuit.com/public/v0.2b/{plan["id"]}/stops:import',
    auth=HTTPBasicAuth(api_key, ""),
    json=stop_data,
)

# With proper addresses the above request will return a response similar to the
# following:
# {
#   "success": [
#     "plans/FQ95Ex714KYeojkeIm77/stops/vgsTiQi85ueWRs1JnXx7",
#     "plans/FQ95Ex714KYeojkeIm77/stops/q0HUM8SwBPt8n3pYZOeO"
#   ],
#   "failed": []
# }
stops = stops_import_response.json()
print(stops)

# If you wish to retrieve more information about one of the create stops you can
# issue a GET request for it:
stop_get_response = requests.get(
    f'https://api.getcircuit.com/public/v0.2b/{stops["success"][0]}',
    auth=HTTPBasicAuth(api_key, ""),
)

# The response will return information about the stop.
stop_info = stop_get_response.json()
print(stop_info)

curl

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