Trackers

Retrieve Trackers

Retrieving a single tracker use the id of the tracker to get it. When you are retrieving multiple trackers, there are additional search and filter options available.

Retrieve Tracker

GET

`/v1/trackers/:tracker`

Get a single tracker using its id.

        const res = await fetch("https://api.packagex.io/v1/tracker/track_czhgjrk5JaVvyATPDbyURp", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const tracker = res.data;

List Trackers

Example

GET

`/v1/trackers`

When you want to retrieve multiple trackers, your data property on the result will always be an array even if you don't have any trackers. The trackers are returned in descending order, meaning the latest tracker that was created will be first.

        const response = await fetch("https://api.packagex.io/v1/trackers", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const trackers = response.data;
const pagination = response.pagination;

Pagination

If the has_more property on the pagination object is set to true, you know there are more deliveries in the database that have not been returned to you. The pagination object also has a page property indicating your current offset and a limit property. The total_count property in pagination returns the the total number of deliveries in the database.

By default the page is set to 1 and the limit is 25.

If we want to query for deliveries 26 - 50, we would request page 2 with a query parameter.

        const response = await fetch("https://api.packagex.io/v1/deliveries?page=2&limit=25", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const trackers = response.data;
const pagination = response.pagination;

Filter

You can filter trackers by location_id, statuses, rate_types and recipient_contact_id.

location_id - Add the ID of one of your locations to get all of the deliveries currently mapped to that location. For example: location_id=loc_czhgjrk5JaVvyATPDbyURp
statuses - A comma separated list of shipment statuses. Keep in mind comma's in URLs are encoded as %2C, so we recommend using your platforms native URL encoding library. For example: statuses=delivered,picked_up

        const response = await fetch(
  "https://api.packagex.io/v1/trackers?location_id=loc_czhgjrk5JaVvyATPDbyURp&statuses=delivered,picked_up&page=3",
  {
    method: "GET",
    headers: {
      "PX-API-KEY": process.env.PX_API_KEY,
      "Content-Type": "application/json",
    },
  }
).then((res) => res.json());

const trackers = response.data;
const pagination = response.pagination;

Sorting

Sorting describes in what order you want your responses to come in. You can select an available property by which to sort, as well as the direction.

order_by - The property by which to sort. Available properties are: created_at , updated_at , estimated_delivery_at
direction - The direction to sort. Available directions are: asc and desc

By default, trackers will be sorted by in descending order, meaning the most recently created will be first.

        const response = await fetch("https://api.packagex.io/v1/trackers?order_by=created_at&direction=desc", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const deliveries = response.data;
const pagination = response.pagination;

Search

There are times when filtering is not enough and you want to find a specific tracker by some other attribute. In this case, you can do a fuzzy, typo-tolerant search of every tracker in the database. Below are the properties that are supported by our full text search for trackers.

id
tracking_number
sender.name
sender.phone
sender.email
sender.address.formatted_address
recipient.name
recipient.phone
recipient.email
recipient.address.formatted_address

To search, simply provide a string to search by using the search query param. If you want to highlight matching search results for a frontend, we provide a special property for search-returned tracker objects called _search which will have the matched text surrounded with <mark> handles.

Ordering Search Results

By default, search results are ordered by relevance. However, if you include an order_by parameter along with your search query, the results will be ordered by the specified property instead of by relevance.

Relevance Score

Relevance scores are included in the search results by default. Note that this could add up to 10ms of extra time to the request.

        const response = await fetch("https://api.packagex.io/v1/trackers?search=jamie%jones", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const tracker = response.data[0]; //Highest relevance score
console.log(tracker._search); //Special _search property

Retrieve Trackers