Economy

Get a US importer's suppliers and shipments

Get a US importer's sea shipments by company name: its suppliers, products by HS code, monthly volumes, ports, carriers and latest bills of lading.

GET/v1/economy/imports
1credit
x-api-keystringheader

API key (`sfk_...`)

Parameters
1
companystringrequiredquery

The importer: a brand, e.g. `Nike`, a name as it appears on shipping documents, e.g. `Nike Usa`, or the `company.id` of an earlier answer, e.g. `nike-usa`. Endings such as Inc, LLC and USA are ignored when matching.

min 2 chars · max 200 chars

Response fields
150

Endpoint-specific response payload.

datalookupStatus
string

`not_found` when no US importer's filed name matches.

one of: found, not_found

dataselection
stringnullable

How the importer was chosen: its id, an exact name, a name starting with yours, or the largest importer among the matches.

one of: id_match, name_match, partial_match, largest_match, null

Importers whose filed names matched, largest first.

datamatches[]id
string

The importer's id; send it as `company`.

min 1 chars

datamatches[]name
string

Name as filed on the manifests.

min 1 chars

datamatches[]address
stringnullable
datamatches[]country
stringnullable

ISO 3166-1 alpha-2 country of the address.

datamatches[]totalShipments
integernullable

Sea shipments on record.

datamatches[]lastShipmentDate
stringnullable

Latest shipment, `YYYY-MM-DD`.

datamatches[]selected
boolean

True for the importer this answer is about.

The importer.

datacompanyid
string

The importer's id, e.g. `nike-usa`.

min 1 chars

datacompanyname
string

Name as filed, e.g. `Nike Usa`.

min 1 chars

datacompanyaddress
stringnullable
datacompanycity
stringnullable
datacompanycounty
stringnullable
datacompanystate
stringnullable

State or region, e.g. `Oregon`.

datacompanycountry
stringnullable

ISO 3166-1 alpha-2 country of the address, e.g. `US`.

datacompanycountryName
stringnullable
datacompanywebsite
stringnullable

Other names the importer files under.

datacompanyotherNames[]
stringoptional
datacompanyotherAddressesCount
integernullable

Other addresses it files from.

datacompanytotalShipments
integernullable

Sea shipments on record.

datacompanyshipmentsLast12Months
integernullable

Sea shipments in the last 12 months.

datacompanyfirstShipmentDate
stringnullable

First shipment on record, `YYYY-MM-DD`.

datacompanylastShipmentDate
stringnullable

Latest shipment, `YYYY-MM-DD`.

datacompanydataUpdatedAt
stringnullable

When the records were last updated, `YYYY-MM-DD`.

datacompanyestimatedShippingCostUsd
numbernullable

Estimated freight spend over all shipments, US dollars.

datacompanyshippingCostCoveragePercent
numbernullable

Share of shipments the freight estimate covers, percent.

datacompanyavgTeuPerShipment
numbernullable

Average twenty-foot container units per shipment, last 12 months.

datacompanyavgTeuPerMonth
numbernullable

Average twenty-foot container units a month, last 12 months.

datacompanyfullContainerShipments
integernullable

Shipments as full container loads.

datacompanylessThanContainerShipments
integernullable

Shipments as less-than-container loads.

datashipmentsByMonth[]month
string

Month, `YYYY-MM`.

min 7 chars

datashipmentsByMonth[]shipments
integer

≥ 0

datashipmentsByMonth[]weightKg
numbernullable

Total weight in kilograms.

datashipmentsByMonth[]teu
numbernullable

Twenty-foot container units.

Its largest suppliers, most shipments first.

datasuppliers[]id
stringnullable

The supplier's id.

datasuppliers[]name
stringnullable

Supplier name; null where the manifest names none.

datasuppliers[]address
stringnullable
datasuppliers[]city
stringnullable
datasuppliers[]country
stringnullable

ISO 3166-1 alpha-2 country of the supplier's address.

datasuppliers[]countryName
stringnullable
datasuppliers[]shippedFrom
stringnullable

ISO 3166-1 alpha-2 country the goods shipped from.

datasuppliers[]shipments
integernullable

Shipments from this supplier to the importer.

datasuppliers[]shipmentsLast12Months
integernullable

Of those, in the last 12 months.

datasuppliers[]weightKg
numbernullable

Total weight shipped, kilograms.

datasuppliers[]teu
numbernullable

Twenty-foot container units shipped.

Leading HS codes of what it ships, e.g. `6404.11`.

datasuppliers[]hsCodes[]
stringoptional

What it ships to the importer, by HS chapter.

datasuppliers[]productChapters[]chapter
stringnullable

2-digit HS chapter; null for the rest.

datasuppliers[]productChapters[]name
stringnullable
datasuppliers[]productChapters[]shipments
integer

≥ 0

datasuppliers[]productChapters[]percent
numbernullable

Share of its shipments.

datasuppliers[]productDescription
stringnullable

Words from its shipments' descriptions, as recorded.

The supplier's largest US customers.

datasuppliers[]otherCustomers[]name
stringnullable
datasuppliers[]otherCustomers[]shipments
integernullable
datasuppliers[]otherCustomers[]shipmentsLast12Months
integernullable
datasuppliersTruncated
boolean

True when it has more suppliers than the 50 listed.

What it imports, by HS chapter, most shipments first.

dataproducts[]hsCode
string

HS code: chapter, heading or subheading.

min 1 chars

dataproducts[]description
stringnullable
dataproducts[]shipments
integer

≥ 0

dataproducts[]weightKg
numbernullable
dataproducts[]teu
numbernullable

4-digit headings in the chapter, each with its subheadings.

dataproducts[]headings[]hsCode
string

HS code: chapter, heading or subheading.

min 1 chars

dataproducts[]headings[]description
stringnullable
dataproducts[]headings[]shipments
integer

≥ 0

dataproducts[]headings[]weightKg
numbernullable
dataproducts[]headings[]teu
numbernullable
dataproducts[]headings[]subheadings[]hsCode
string

HS code: chapter, heading or subheading.

min 1 chars

dataproducts[]headings[]subheadings[]description
stringnullable
dataproducts[]headings[]subheadings[]shipments
integer

≥ 0

dataproducts[]headings[]subheadings[]weightKg
numbernullable
dataproducts[]headings[]subheadings[]teu
numbernullable

Shipments by the country the goods came from.

dataimportsByCountry[]country
string

Origin country name.

min 1 chars

dataimportsByCountry[]continent
stringnullable
dataimportsByCountry[]shipments
integer

≥ 0

Port pairs its goods travel between, most shipments first.

datashippingLanes[]exitPort
stringnullable
datashippingLanes[]exitCountry
stringnullable
datashippingLanes[]entryPort
stringnullable
datashippingLanes[]entryRegion
stringnullable
datashippingLanes[]shipments
integer

≥ 0

datashippingLanes[]weightKg
numbernullable
datashippingLanes[]teu
numbernullable
datashippingLanes[]estimatedShippingCostUsd
numbernullable

Ocean carriers it ships with.

datacarriers[]code
stringnullable

Carrier SCAC code.

datacarriers[]name
stringnullable
datacarriers[]shipments
integer

≥ 0

datacarriers[]shipmentsLast12Months
integernullable

Latest shipments, newest first.

datarecentShipments[]date
stringnullable

Arrival date, `YYYY-MM-DD`.

datarecentShipments[]billOfLading
stringnullable

Bill of lading number.

datarecentShipments[]masterBillOfLading
stringnullable
datarecentShipments[]houseBillOfLading
stringnullable
datarecentShipments[]billType
stringnullable

Kind of bill.

one of: house, master, regular, null

datarecentShipments[]supplierId
stringnullable
datarecentShipments[]supplierName
stringnullable

Shipper; null when not named.

datarecentShipments[]supplierCountry
stringnullable

ISO 3166-1 alpha-2 country the goods came from.

datarecentShipments[]description
stringnullable

Goods as described.

datarecentShipments[]weightKg
numbernullable
datarecentShipments[]quantity
numbernullable
datarecentShipments[]quantityUnit
stringnullable

Unit of `quantity`, e.g. `CTN`.

datarecentShipments[]containers
integernullable
datarecentShipments[]route
stringnullable

Ocean route, e.g. `Asia, Transpacific`.

datarecentShipments[]estimatedShippingCostUsd
numbernullable
datarecentShipments[]declaredValueUsd
numbernullable

Cost, insurance and freight value declared on the manifest, when declared.

datarecentShipmentsTotal
integernullable

All its shipments on record; `recentShipments` lists only the latest 50.

Recent shipments with a declared value, newest first.

datavaluedShipments[]date
stringnullable

Arrival date, `YYYY-MM-DD`.

datavaluedShipments[]billOfLading
stringnullable

Bill of lading number.

datavaluedShipments[]masterBillOfLading
stringnullable
datavaluedShipments[]houseBillOfLading
stringnullable
datavaluedShipments[]billType
stringnullable

Kind of bill.

one of: house, master, regular, null

datavaluedShipments[]supplierId
stringnullable
datavaluedShipments[]supplierName
stringnullable

Shipper; null when not named.

datavaluedShipments[]supplierCountry
stringnullable

ISO 3166-1 alpha-2 country the goods came from.

datavaluedShipments[]description
stringnullable

Goods as described.

datavaluedShipments[]weightKg
numbernullable
datavaluedShipments[]quantity
numbernullable
datavaluedShipments[]quantityUnit
stringnullable

Unit of `quantity`, e.g. `CTN`.

datavaluedShipments[]containers
integernullable
datavaluedShipments[]route
stringnullable

Ocean route, e.g. `Asia, Transpacific`.

datavaluedShipments[]estimatedShippingCostUsd
numbernullable
datavaluedShipments[]declaredValueUsd
numbernullable

Cost, insurance and freight value declared on the manifest, when declared.

Where the data comes from and how to credit it when you reuse it.

datasourcepublisher
string

Who publishes the data, e.g. `Eurostat`.

min 1 chars

datasourcedataset
stringnullable

The publisher's dataset code, when it has one.

datasourcetitle
stringnullable

The dataset's title.

datasourceupdatedAt
stringnullable

When the publisher last updated the data, ISO 8601.

datasourceurl
stringnullable

Where the data can be viewed.

datasourcelicence
string

The terms the data is published under.

min 1 chars

datasourceattribution
string

Credit line the licence asks for when you reuse or publish the data.

min 1 chars

Metadata describing the request and billing outcome.

metarequestId
string

Unique request identifier for tracing this API call.

min 1 chars

metacreditsCharged
integer

Credits charged for this request.

≥ 0

metaversion
string

Public API version that served the response.

one of: v1

metastale
booleanoptional

Present, and `true`, only when the source couldn't be reached and this is the last good answer for the same request instead, up to 24 hours old. Absent on every live answer.

one of: true

metafetchedAt
stringoptional

When a stale answer (`stale: true`) was originally fetched (ISO 8601, UTC). Absent on every live answer.

Code example

curl "https://api.socialfetch.dev/v1/economy/imports?company=Nike" \
  -H "x-api-key: YOUR_API_KEY"

Responses

The importer's record, or not_found.