Onfleet Python Wrapper

Read this document in another language: English, 正體中文

Visit our blog post on the API wrapper project to learn more about our initiatives. If you have any questions, please reach out to Onfleet by submitting an issue here or contact [email protected]

Table of Contents

• Onfleet Python Wrapper
  • Table of Contents
  • Synopsis
  • Installation
  • Usage
    • Throttling
    • Responses
    • Supported CRUD Operations
      • GET Requests
        • Examples of get()
        • Examples of get(param)
        • Examples of getByLocation:
      • POST Requests
        • Examples of create()
      • PUT Requests
        • Examples of update()
        • Examples of updateSchedule()
        • Examples of insertTask()
      • DELETE Requests
        • Examples of deleteOne()

Synopsis

The Onfleet Python library provides convenient access to the Onfleet API.

Installation

pip install pyonfleet

Usage

Before using the API wrapper, you will need to obtain an API key from your organization admin. Creation and integration of API keys are performed through the Onfleet dashboard.

To authenticate, you will also need to create a file named .auth.json under your working directory, this is where you will store your API credentials.

The format of .auth.json is shown below:

{
    "API_KEY": "<your_api_key>", 
}

You can also opt in to not store your API key here and use it on the fly instead.

Once the Onfleet object is created, you will get access to all the API endpoints as documented in the Onfleet API documentation. Here are some usage case:

from onfleet import Onfleet

api = Onfleet() # if .auth.json was provided
api = Onfleet(api_key="<your_api_key>") # if no .auth.json was provided

Throttling

Rate limiting is enforced by the API with a threshold of 20 requests per second across all your organization's API keys, learn more about it here.

Responses

The pyonfleet API wrapper returns the body of a Response object.

Supported CRUD Operations

The base URL for the Onfleet API is https://onfleet.com/api/v2, here are the supported CRUD operations for each endpoint:

<endpoint>	GET	POST	PUT	DELETE
Admins/Administrators	get()	create(body), matchMetadata(body)	update(id, body)	deleteOne(id)
Containers	get(workers=id), get(teams=id), get(organizations=id)	x	update(id, body)	x
Destinations	get(id)	create(body), matchMetadata(body)	x	x
Hubs	get()	create(body)	update(id, body)	x
Organization	get(), get(id)	x	insertTask(id, body)	x
Recipients	get(id), get(name), get(phone)	create(body), matchMetadata(body)	update(id, body)	x
Tasks	get(queryParams), get(id), get(shortId)	create(body), clone(id), forceComplete(id), batch(body), autoAssign(body), matchMetadata(body)	update(id, body)	deleteOne(id)
Teams	get(), get(id), getWorkerEta(id, queryParams)	create(body), autoDispatch(id, body)	update(id, body), insertTask(id, body)	deleteOne(id)
Webhooks	get()	create(body)	x	deleteOne(id)
Workers	get(), get(queryParams), get(id), getByLocation(queryParams), getSchedule(id)	create(body), setSchedule(id, body), matchMetadata(body)	update(id, body), insertTask(id, body)	deleteOne(id)

GET Requests

To get all the documents within an endpoint:

get()

Examples of get()

api.workers.get()
api.workers.get(queryParams="")

Option to use query parameters for some certain endpoints, refer back to API documents for endpoints that support query parameters:

api.workers.get(queryParams="phones=<phone_number>")

or

api.workers.get(queryParams={"phones":"<phone_number>"})

To get one of the document within an endpoint, specify the param that you wish to search by:

get(param=<some_param>)

Examples of get(param)

api.workers.get(id="<24_digit_id>")
api.workers.get(id="<24_digit_id>", queryParams={"analytics": "true"})
api.tasks.get(shortId="<shortId>")
api.recipients.get(phone="<phone_number>")
api.recipients.get(name="<recipient_name>")

api.containers.get(workers="<worker_id>")
api.containers.get(teams="<team_id>")
api.containers.get(organizations="<org_id>")

To get a driver by location, use the getByLocation function:

getByLocation(queryParams=<some_param>)

Examples of getByLocation:

params = {"longitude":"-122.4","latitude":"37.7601983","radius":"6000"}
api.workers.getByLocation(queryParams=params)

POST Requests

To create a document within an endpoint:

create(body="<body_object>")

Examples of create()

driver = {
  "name": "A Swartz Test",
  "phone": "+16173428853",
  "teams": ["<a_team_id>", "<a_team_id> (optional)..."],
  "vehicle": {
    "type": "CAR",
    "description": "Tesla Model S",
    "licensePlate": "FKNS9A",
    "color": "purple",
  }
}

api.workers.create(body=driver)

Extended POST requests include clone, forceComplete, batchCreate, autoAssign on the tasks endpoint, setSchedule on the workers endpoint, autoDispatch on the teams endpoint, and matchMetadata on all supported entities:

api.tasks.clone(id="<24_digit_id>")
api.tasks.forceComplete(id="<24_digit_id>", body="<completion_details>")
api.tasks.batchCreate(body="<task_object_get>")
api.tasks.autoAssign(body="<auto_assign_object>")

api.workers.setSchedule(id="<24_digit_id>", body="<schedule_object>")
api.teams.autoDispatch(id="<24_digit_id>", body="<dispatch_config>")
api.<entity>.matchMetadata(body="<array_of_metadata_object>")

For more details, check our documentation on clone, forceComplete, batchCreate, autoAssign, setSchedule, and matchMetadata.

PUT Requests

To update a document within an endpoint:

update(id="<24_digit_id>", body="<body_object>")

Examples of update()

updateBody = {
    "name": "New Driver Name",
}
api.workers.update(id="<24_digit_id>", body=updateBody)

Examples of updateSchedule()

api.workers.updateSchedule(id="<24_digit_id>", body=newSchedule)

For more details, check our documentation on updateSchedule

Examples of insertTask()

api.workers.insertTask(id="kAQ*G5hnqlOq4jVvwtGNuacl", body="<body_object>")

DELETE Requests

To delete a document within an endpoint:

deleteOne(id="<24_digit_id>")

Examples of deleteOne()

api.workers.deleteOne(id="<24_digit_id>")