Skip to content
Developer docs: all pages

GET/api/v1/trade/flows

Trade flows by commodity, country and port

Official trade statistics by month, per source: UK customs trade by port (HMRC Overseas Trade Statistics, HS2, GBP); EU member states' trade by partner country and HS code (Eurostat Comext, aggregated from CN8 to HS4, EUR, net mass, with intra-EU and extra-EU split, top reporting countries, partners, commodities and country pairs, and the change on the month and on the year); Canada's trade carried by water by partner and product group (Statistics Canada, CAD, NAPCS not HS), under `canadaByMode`; US Census port data when loaded; and official port throughput (Eurostat, Port of Los Angeles) when a port is given. Values stay in each source's own currency and weight basis; sources are never converted or added. Comext needs at least one of hs, reporter or country and its window ends at the newest month held: up to 24 months for one HS4 code or a reporter and partner pair, 3 months for a chapter, a reporter alone or a partner alone (`hints` says when a request was not served and why). Other sources return at most 36 months. Sources not licensed for API use are under `withheld` with the reason; a source with nothing for the request is under `noData`. These are reported government statistics, each series with its source and licence; nothing here is a voyage model or an estimate of what a ship carries. Sources withheld for rights reasons are listed as withheld with the reason, and no plan unlocks them. Available on every API plan, including the free Sandbox. A server-side release switch is checked on every request: while it is off for your account this endpoint answers 404 (not_found), free.

1 creditKey required

Parameters
NameInDescription
hsqueryHS code of 2, 4 or 6 digits (default: HS2 totals for the port-level sources). Comext is held at HS4: give 4 digits, or 2 for a chapter.
countryqueryPartner country, ISO 3166-1 alpha-2. For Comext, GB also matches Eurostat's XU and XI.
reporterqueryReporting country, ISO 3166-1 alpha-2: an EU member state for Comext, GB for HMRC, US for Census, CA for Statistics Canada. Sources of other countries are then not read.
portqueryReporting port UN/LOCODE (also returns port throughput; country-level sources are not read).
directionqueryimport or export (default both).
monthsqueryMonths back, 1 to 36 (default 12).
Request
curl -H "Authorization: Bearer $VOYDAR_API_KEY" \
  https://www.voydar.com/api/v1/trade/flows?hs=2709&reporter=DE&months=12
Response (abridged)
{
  "type": "port_list",
  "apiVersion": "1",
  "count": 2,
  "data": [
    { "unlocode": "NLAMS", "name": "Amsterdam", "country": "NL", "coordinates": { "lat": 52.4, "lon": 4.82, "source": "unlocode" },
      "api": "https://www.voydar.com/api/v1/ports/nlams" },
    { "unlocode": "NLRTM", "name": "Rotterdam", "country": "NL", "coordinates": { "lat": 51.9, "lon": 4.5, "source": "nga_wpi" },
      "api": "https://www.voydar.com/api/v1/ports/nlrtm" }
  ],
  "next": "https://www.voydar.com/api/v1/ports?country=NL&limit=2&cursor=NLRTM",
  "withheld": [],
  "attribution": [ "…" ], "license": [ "…" ], "sources": ["nga_wpi", "unlocode"]
}