# dzship — The Free Shipping API for Algeria (Yalidine, ZR Express, Maystro, NOEST, Ecotrack in One Integration)

Every developer who has built for Algerian e-commerce knows the pain: each delivery company ships its own API. Different authentication, different field names, statuses in French, Arabic, or bare numbers — and documentation that ranges from thin to wrong. Integrating one courier takes days; supporting five means maintaining five fragile integrations forever.

Today we're fixing that for everyone. **[dzship](https://freeship.dzbuild.com) is a free, public shipping API for Algeria** — one request shape to create, track, and price cash-on-delivery parcels with **Yalidine, ZR Express, Maystro, NOEST, and 80+ couriers on the Ecotrack platform** (DHD, Conexlog, MSM Go, World Express and more).

No signup. No API key. No cost.

## Why we made it free

DZBuild moves real COD orders across all 58 wilayas every day, and our platform already speaks to 102+ delivery integrations. dzship packages that battle-tested shipping engine as a public service, because we believe Algerian tech grows when the boring, painful infrastructure is a solved problem — for everyone, not just our merchants.

A stronger developer ecosystem means more online stores, more tools, more business moving online. That's the mission: **taking Algerian tech to the next level and making business life easier.** Shipping is our contribution to the commons.

## One request, any courier

You bring your own courier account credentials with each call — they are **never stored** — and dzship translates to whatever dialect that courier speaks:

```
curl -X POST https://freeship.dzbuild.com/v1/orders \

  -H 'Content-Type: application/json' -d '{

    "courier":     "yalidine",

    "credentials": { "apiId": "YOUR_ID", "apiToken": "YOUR_TOKEN" },

    "order": {

      "recipient": {

        "fullName":    "Amine Bouzid",

        "phone":       "0551234567",

        "wilayaCode":  16,

        "communeName": "Bab Ezzouar"

      },

      "deliveryType": "home",

      "productList":  "Sneakers Air x1",

      "codAmount":    4500

    }

  }'

# → 201 { "trackingNumber": "yal-ABC123", "status": "created" }
```

Switching courier = switching the `courier` key and the credentials. The rest of your code doesn't change. Tracking works the same way and returns **one canonical status vocabulary** across all couriers (`picked_up`, `in_transit`, `out_for_delivery`, `delivered`…), so your dashboard never has to parse "Sorti en livraison" again.

## Ready-made clients for your stack

You don't even need to write the HTTP calls. The [dzship GitHub repository](https://github.com/DZBuild-com/dzship) ships MIT-licensed clients:

* **Node.js** — `npm install dzship` ([on npm](https://www.npmjs.com/package/dzship)): zero dependencies, TypeScript types included.

  ```
  import dzship from 'dzship';



  const client = dzship({

    courier: 'yalidine',

    credentials: { apiId: process.env.YAL_ID, apiToken: process.env.YAL_TOKEN },

  });

  const { trackingNumber } = await client.createOrder({ /* … */ });
  ```

* **PHP** — a single-file class that runs on any shared hosting (Laravel and WooCommerce recipes included).

* **Python** — a single-file, standard-library-only module for Django, Flask, FastAPI, or a plain script.

* **Google Sheets** — an Apps Script snippet for the classic "200 orders in a spreadsheet" workflow.

The [integration guide](https://github.com/DZBuild-com/dzship/blob/main/docs/integrating.md) covers every path, and the repo also holds **field guides for each courier** — the traps we learned the expensive way, documented so you don't have to.

## A free dataset too: every wilaya and commune

Bad address data kills deliveries. The repo includes a **public-domain (CC0) dataset of all 58 wilayas and 1,541 communes** — French and Arabic names, current post-2021 division, in JSON and CSV. Use it for your checkout forms, no attribution needed:

```
const wilayas = await fetch(

  'https://raw.githubusercontent.com/DZBuild-com/dzship/main/data/wilayas.json'

).then((r) => r.json());
```

## Fair use, worldwide

dzship is available worldwide and protected by fair-use limits (30 orders/hour per IP, generous tracking quotas) so it stays fast and free for everyone. Full reference, error codes and limits: [freeship.dzbuild.com](https://freeship.dzbuild.com).

One security rule: call it from your **server**, never from a browser or mobile app — your courier credentials must stay secret.

## When you need more than shipping

dzship is the shipping layer. If you're building a whole store for an Algerian merchant, [DZBuild](https://dzbuild.com) is the rest: Arabic/French storefronts, landing pages, COD order management with confirmation workflows, 102+ couriers pre-wired, stock, and analytics — live in minutes, no code.

Either way, ship something. That's the point.

**Start here:** [freeship.dzbuild.com](https://freeship.dzbuild.com) · [github.com/DZBuild-com/dzship](https://github.com/DZBuild-com/dzship) · `npm install dzship`