Eagle1 Whereis API

Goal

Built for developers. Fully open-source. Track any shipment with one simple API.

Problem

Since different logistics providers have their own APIs and data formats, integrating various logistics data poses a significant challenge for app developers.

Why we built this

During COVID, we wanted to systematically track critical packages containing masks without checking each carrier's website manually. We learned that integrating with various logistics carriers was nearly impossible. It took way too much time and brain cells to understand and connect their APIs. Thus, we are fixing it the open-source way. Now we can help ourselves and fellow developers stay prepared for the next global supply chain event.

Design

1. This prototype is written in TypeScript and runs on the Deno runtime.
2. We have defined standard status codes and a consistent format for global logistics data.
3. Initially it supports two logistics operators: FedEx and SF Express, with a future roadmap planned. Code review is on DeepWiki.

Intentions

• Beyond Simple Mapping: Transform raw carrier data into meaningful, standardized information.
• Developer-Centric: Provide consistent, easy-to-understand API responses.
• Continuous Improvement: Mapping rules evolve based on real-world data patterns via a two-stage process: (Stage 1: rule-based mapping; Stage 2: AI-assisted enhancement).

Documentation

• Wiki
• Real-world use case

Examples

Track locations over time

cURL

curl https://api.eg1.io/v0/whereis/{{trackingID}} -H "Authorization: Bearer YOUR-TOKEN"

{{trackingID}} uses the structure operatorCode-trackingNum. Example: a FedEx trackingID is fdx-888877776666.

TypeScript

const url = "https://api.eg1.io/v0/whereis/{{trackingID}}";
const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: "Bearer YOUR-TOKEN",
  },
});

Response (consistent format for all logistics providers)

{
  "entity": {
    "id": "fdx-888877776666",
    "type": "waybill",
    "uuid": "37ebed64-f8fb-457b-be21-5df1f519fbc4",
    "createdAt": "2024-11-11T14:16:48-06:00",
    "additional": {
      "origin": "San Francisco CA United States",
      "destination": "CENTRAL  Hong Kong SAR, China",
      "isCrossBorder": true,
      "processingTimeMs": 3.7
    }
  },
  "events": [{
    "status": 3000,
    "what": "Transport Bill Created",
    "whom": "FedEx",
    "when": "2024-11-11T14:16:48-06:00",
    "where": "Customer location",
    "notes": "Shipment information sent to FedEx",
    "additional": {
      "trackingNum": "888877776666",
      "operatorCode": "fdx",
      "dataProvider": "FedEx",
      "updateMethod": "manual-pull",
      "updatedAt": "2025-02-20T12:23:43.892Z"
    }
  }]
}

---

The latest status and location

cURL

curl https://api.eg1.io/v0/status/{{trackingID}}

TypeScript

const url = 'https://api.eg1.io/v0/status/{{trackingID}}';
const response = await fetch(url, {
  method: "GET"
});

Response

{
  "id": "fdx-888877776666",
  "status": 3000,
  "what": "Transport Bill Created",
  "whom": "FedEx",
  "when": "2024-11-11T14:16:48-06:00",
  "where": "Customer location",
  "notes": "Shipment information sent to FedEx"
}

---

Getting started

There are only three commands to deploy locally with Docker! Detailed, step-by-step instructions can be found in the How-to Guide.

git clone https://github.com/eagle1-sys/whereis-api-v0
cd whereis-api-v0
make whereis

That's it. Enjoy!