Inventory API Access
Integrate Oceanbox’s published container offers into your own inventory and buyer matching system.
Read only · JSON · v1 · Customer API keyQuick 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"
}]
}
| Field | Meaning |
|---|---|
| published_date | Source date shown on the inventory page; not a promise of live availability. |
| snapshot_id | Changes when public offer content or source date changes. |
| offer_id | Public offer identifier. Stable for price/quantity changes; spec, location, depot, terms or ETA changes may produce a new ID. |
| location | Public location label. The feed may include Canadian and US cities; resolve geography explicitly before matching buyers. |
| quantity / price | Published quantity and price per container. Currency is explicit when known, otherwise null; do not assume USD for null. |
| condition / eta | Public specification and arrival/availability text. ETA may describe multiple batches; do not treat all quantity as immediately available. |
| trans_method | Published transaction method. Match pickup and other terms explicitly. |
| depot_address | Public 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.
| 200 | Complete JSON inventory snapshot |
| 304 | Unchanged; keep your previous snapshot |
| 400 | Unsupported query parameters or request body |
| 401 | Missing, invalid, expired or revoked key; contact Oceanbox |
| 405 | Unsupported method; use GET |
| 429 | Rate/quota protection; retry after the stated delay |
| 503 | Public 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.