Code Examples

Copy-paste snippets for the most common stacks. All examples hit the production endpoint https://shipshim.com/api/v1/track and use Authorization: Bearer YOUR_API_KEY for authentication. See API Reference for the full response schema, including the confidence score and the matches array that lists all carriers whose patterns matched.

cURL

curl -X POST https://shipshim.com/api/v1/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"tracking_number": "1Z999AA10123456784"}'

With a country hint to bias the match:

curl -X POST https://shipshim.com/api/v1/track \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tracking_number": "RR123456789DE", "country": "DE"}'

JavaScript / Node.js

const res = await fetch('https://shipshim.com/api/v1/track', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({ tracking_number: '1Z999AA10123456784' }),
});

const data = await res.json();

if (!res.ok) {
  // 401 / 403 / 404 / 422 / 429 / 500
  console.error(`[${res.status}] ${data.error}: ${data.message}`);
  return;
}

console.log(`Carrier: ${data.carrier} (${data.confidence}% confidence)`);
console.log(`URL: ${data.tracking_url}`);

if (data.ambiguous) {
  console.warn('Ambiguous match — consider passing a `carrier` or `country` hint.');
  console.table(data.matches);
}

Python

import requests

resp = requests.post(
    'https://shipshim.com/api/v1/track',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Accept': 'application/json',
    },
    json={'tracking_number': '1Z999AA10123456784'},
)
data = resp.json()

if not resp.ok:
    raise SystemExit(f"[{resp.status_code}] {data.get('error')}: {data.get('message')}")

print(f"Carrier: {data['carrier']} ({data['confidence']}% confidence)")
print(f"URL: {data['tracking_url']}")

if data.get('ambiguous'):
    for m in data['matches']:
        print(f"  - {m['carrier']} ({m['country']}): {m['confidence']}%")

PHP

<?php

$ch = curl_init('https://shipshim.com/api/v1/track');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['tracking_number' => '1Z999AA10123456784']),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($body, true);

if ($status !== 200) {
    throw new RuntimeException("[{$status}] {$data['error']}: {$data['message']}");
}

echo "Carrier: {$data['carrier']} ({$data['confidence']}% confidence)\n";
echo "URL: {$data['tracking_url']}\n";

Ruby

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://shipshim.com/api/v1/track')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

req = Net::HTTP::Post.new(uri)
req['Authorization'] = 'Bearer YOUR_API_KEY'
req['Content-Type'] = 'application/json'
req['Accept'] = 'application/json'
req.body = { tracking_number: '1Z999AA10123456784' }.to_json

res = http.request(req)
data = JSON.parse(res.body)

if res.code != '200'
  abort("[#{res.code}] #{data['error']}: #{data['message']}")
end

puts "Carrier: #{data['carrier']} (#{data['confidence']}% confidence)"
puts "URL: #{data['tracking_url']}"

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]string{"tracking_number": "1Z999AA10123456784"})

    req, _ := http.NewRequest("POST", "https://shipshim.com/api/v1/track", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Accept", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)

    if resp.StatusCode != 200 {
        fmt.Printf("[%d] %s: %s\n", resp.StatusCode, data["error"], data["message"])
        return
    }
    fmt.Printf("Carrier: %v (%.0f%% confidence)\n", data["carrier"], data["confidence"])
    fmt.Printf("URL: %v\n", data["tracking_url"])
}

Laravel / PHP HTTP Client

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.shipshim.key'))
    ->acceptJson()
    ->post('https://shipshim.com/api/v1/track', [
        'tracking_number' => '1Z999AA10123456784',
    ]);

$response->throw();

$data = $response->json();
logger()->info('Resolved carrier', [
    'carrier' => $data['carrier'],
    'confidence' => $data['confidence'],
    'url' => $data['tracking_url'],
]);

TypeScript types

For type-safe consumers:

type TrackMatch = {
  carrier: string;
  country: string;       // ISO code, or "INT"
  confidence: number;    // 0..100
  tracking_url: string;
};

type TrackSuccess = {
  tracking_number: string;
  carrier: string;
  country: string;
  tracking_url: string;
  confidence: number;
  ambiguous?: true;      // present only when multiple carriers matched
  message?: string;      // present with `ambiguous`
  matches: TrackMatch[];
};

type TrackError = {
  error: 'not_found' | 'unauthorized' | 'account_suspended' | 'rate_limit_exceeded';
  message: string;
  limit?: number;        // present on rate_limit_exceeded
  used?: number;         // present on rate_limit_exceeded
};

type TrackResponse = TrackSuccess | TrackError;