← Public inventory

Inventory API Access

Integrate Oceanbox’s published container offers into your own inventory and buyer matching system.

Read only · JSON · v1 · Customer API key

Quick start

Ask your Oceanbox contact for a dedicated key. Requests must come from your server; never embed the key in browser code, mobile apps, URLs, or public repositories.

curl --fail-with-body 'https://inventory.oceanbox.cn/api/v1/inventory' \
  -H 'Authorization: Bearer YOUR_API_KEY'

No query parameters or request body are supported. The feed includes only inventory published on this site.

Response contract

This example is illustrative and is not an offer.

{
  "schema_version": "1.0",
  "source_url": "https://inventory.oceanbox.cn/",
  "published_date": "Nov 07, 2026",
  "snapshot_id": "<content hash>",
  "sync_mode": "full_snapshot",
  "total": 1,
  "notice": "Confirm availability, currency and final terms before booking.",
  "items": [{
    "offer_id": "<public offer identifier>",
    "location": "Chicago",
    "container_type": "40HC",
    "condition": "1-Trip/RAL7016",
    "quantity": 3,
    "price": 2500.0,
    "currency": "USD",
    "trans_method": "Pickup",
    "eta": "In Depot",
    "depot_address": "Example public depot"
  }]
}
FieldMeaning
published_dateSource date shown on the inventory page; not a promise of live availability.
snapshot_idChanges when public offer content or source date changes.
offer_idPublic offer identifier. Stable for price/quantity changes; spec, location, depot, terms or ETA changes may produce a new ID.
locationPublic location label. The feed may include Canadian and US cities; resolve geography explicitly before matching buyers.
quantity / pricePublished quantity and price per container. Currency is explicit when known, otherwise null; do not assume USD for null.
condition / etaPublic specification and arrival/availability text. ETA may describe multiple batches; do not treat all quantity as immediately available.
trans_methodPublished transaction method. Match pickup and other terms explicitly.
depot_addressPublic depot label or address, possibly null.

Synchronization

Poll every 15 minutes. Each 200 response is a complete replacement snapshot; upsert current offers and remove previous Oceanbox offers absent from the new snapshot. An empty items array means there are no published offers. Preserve your own inventory separately.

Send the last ETag in If-None-Match to get 304 Not Modified. Keep existing data on 304. A successful publication updates the page and feed atomically; API caching may delay visibility by up to 30 seconds.

On any failed request, keep the previous successful snapshot and clearly mark its source date/staleness. Do not clear stock, and do not treat an error page as an empty feed. Confirm availability, currency, transport and final terms with Oceanbox before booking.

Limits and errors

Your assigned minute and daily quotas are provided with the key. Daily quotas reset at midnight in Asia/Shanghai. Conditional requests (304) and upstream errors consume quota. A separate service protection cap may also apply. Follow Retry-After on 429 or 503, and retry with backoff.

200Complete JSON inventory snapshot
304Unchanged; keep your previous snapshot
400Unsupported query parameters or request body
401Missing, invalid, expired or revoked key; contact Oceanbox
405Unsupported method; use GET
429Rate/quota protection; retry after the stated delay
503Public snapshot or API temporarily unavailable; preserve old data

Access and privacy

Keys identify an integration, not an individual person. Oceanbox records per-key request counts, hourly frequency, response status and access timestamps. Latest client software and an IP digest may be recorded. Keys can be independently revoked or rotated. This API cannot modify inventory or the website.

The underlying inventory is already public. Credentials control and meter this supported integration endpoint; they do not make the publicly visible offers confidential.