> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# US Company Imports

> Resolve a US ocean importer within the first 50 company search hits, then return its indexed shipment totals, top 25 suppliers, top 25 HS headings and up to 50 recent bills. Prefer normalized name matches, then whole-word partial matches, then the largest hit by shipment count. All candidate hits and the selection rule are included. This is not an exhaustive name search; supplier_count is unavailable and null. Source-confirmed no matches returns a free 404.

Look up a company in public US ocean-import records indexed by ImportYeti. Supply `company` and optionally `limit` (1–50, default 25). One successful lookup costs **20 credits**, regardless of shipment limit. Exact repeats are cached for 24 hours at zero credits; errors, source-confirmed no records (404), and idempotent replays are free.

The lookup examines **at most 50 source-ranked company search hits**. It prefers a normalized exact name, ignoring spacing and common corporate endings, then a whole-word partial match, then the largest remaining search hit by indexed shipment count. Ties retain source order. For example, `Nike` chooses `Nike Usa` over a smaller filer named `Nike`. `matches` preserves every hit in that fetched window with its native rank and one selected row; `selection` explains the rule. `search_window.complete` is always false because this is not an exhaustive company-registry search. Use a precise filing name to reduce ambiguity.

`company` includes source-indexed lifetime and last-12-month shipment counts, first/last shipment dates, filed address, website and known alternate names. **`supplier_count` is unavailable and remains null**; the adapter does not relabel the fetched supplier window as a total.

`top_suppliers` contains up to 25 suppliers ordered by the source's shipment count, including unnamed suppliers as `name: null`. It preserves country, lifetime/12-month shipment counts, weight in kilograms and four-digit HS headings. `hs_codes` contains the top 25 four-digit headings by shipment count and their chapters.

`recent_shipments` contains up to the requested number of latest source-visible bills (maximum 50), newest first. Each has its date, bill number, supplier/country, product description, weight, container count, quantity/unit and ocean route. Per-shipment `hs_code` is filled only from one explicit, unambiguous HS/HTS-code label in the manifest text. It stays null when absent or ambiguous. Loading/discharge ports remain null; aggregate route tables do not establish per-bill ports.

Only US incoming ocean manifests are represented. Air freight, exports, other countries' trade and withheld manifests are absent. Totals describe the source index; its search and profile snapshots may differ during updates. The adapter validates identity, dates, ordering, duplicate bills and counts. A failed or mismatched source is refunded. Two pinned limited-permission source runs share a 55-second deadline; this verification is not a promise of continuous upstream availability.


## OpenAPI

````yaml GET /economy/imports
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /economy/imports:
    get:
      tags:
        - Economy
      summary: Economy Imports
      description: >-
        Resolve a US ocean importer within the first 50 company search hits,
        then return its indexed shipment totals, top 25 suppliers, top 25 HS
        headings and up to 50 recent bills. Prefer normalized name matches, then
        whole-word partial matches, then the largest hit by shipment count. All
        candidate hits and the selection rule are included. This is not an
        exhaustive name search; supplier_count is unavailable and null.
        Source-confirmed no matches returns a free 404.
      operationId: get_economy_imports
      parameters:
        - name: company
          in: query
          required: true
          example: Nike
          schema:
            type: string
        - name: limit
          in: query
          required: false
          example: 10
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 25
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            Optional nonnegative integer cap on the maximum request hold. A live
            request whose hold exceeds this cap returns 422
            CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
            requested limit; cache hits and successful idempotent replays cost
            zero.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: >-
            Resolve a US ocean importer within the first 50 company search hits,
            then return its indexed shipment totals, top 25 suppliers, top 25 HS
            headings and up to 50 recent bills. Prefer normalized name matches,
            then whole-word partial matches, then the largest hit by shipment
            count. All candidate hits and the selection rule are included. This
            is not an exhaustive name search; supplier_count is unavailable and
            null. Source-confirmed no matches returns a free 404.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          company:
                            type: object
                            properties:
                              name:
                                type: string
                              country:
                                type:
                                  - string
                                  - 'null'
                              country_code:
                                type:
                                  - string
                                  - 'null'
                              address:
                                type:
                                  - string
                                  - 'null'
                              website:
                                type:
                                  - string
                                  - 'null'
                              url:
                                type: string
                              total_shipments:
                                type: integer
                                minimum: 0
                              shipments_last_12_months:
                                type: integer
                                minimum: 0
                              first_shipment_date:
                                type: string
                                format: date
                              last_shipment_date:
                                type: string
                                format: date
                              supplier_count:
                                type: 'null'
                              other_names:
                                type: array
                                items:
                                  type: string
                                maxItems: 1000
                            required:
                              - name
                              - country
                              - country_code
                              - address
                              - website
                              - url
                              - total_shipments
                              - shipments_last_12_months
                              - first_shipment_date
                              - last_shipment_date
                              - supplier_count
                              - other_names
                            additionalProperties: false
                          top_suppliers:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type:
                                    - string
                                    - 'null'
                                url:
                                  type:
                                    - string
                                    - 'null'
                                country:
                                  type:
                                    - string
                                    - 'null'
                                country_code:
                                  type:
                                    - string
                                    - 'null'
                                total_shipments:
                                  type: integer
                                  minimum: 0
                                shipments_last_12_months:
                                  type: integer
                                  minimum: 0
                                total_weight_kg:
                                  type: number
                                  minimum: 0
                                hs_codes:
                                  type: array
                                  items:
                                    type: string
                                  maxItems: 100
                              required:
                                - name
                                - url
                                - country
                                - country_code
                                - total_shipments
                                - shipments_last_12_months
                                - total_weight_kg
                                - hs_codes
                              additionalProperties: false
                            maxItems: 25
                          hs_codes:
                            type: array
                            items:
                              type: object
                              properties:
                                code:
                                  type: string
                                description:
                                  type: string
                                chapter:
                                  type: string
                                chapter_description:
                                  type: string
                                shipments:
                                  type: integer
                                  minimum: 0
                              required:
                                - code
                                - description
                                - chapter
                                - chapter_description
                                - shipments
                              additionalProperties: false
                            maxItems: 25
                          recent_shipments:
                            type: array
                            items:
                              type: object
                              properties:
                                date:
                                  type: string
                                  format: date
                                bill_number:
                                  type: string
                                supplier:
                                  type:
                                    - string
                                    - 'null'
                                supplier_country:
                                  type:
                                    - string
                                    - 'null'
                                supplier_country_code:
                                  type:
                                    - string
                                    - 'null'
                                product_description:
                                  type:
                                    - string
                                    - 'null'
                                weight_kg:
                                  type: number
                                  minimum: 0
                                container_count:
                                  type: integer
                                  minimum: 0
                                quantity:
                                  type: number
                                  minimum: 0
                                quantity_unit:
                                  type:
                                    - string
                                    - 'null'
                                route:
                                  type:
                                    - string
                                    - 'null'
                                hs_code:
                                  type:
                                    - string
                                    - 'null'
                                port_of_loading:
                                  type: 'null'
                                port_of_discharge:
                                  type: 'null'
                              required:
                                - date
                                - bill_number
                                - supplier
                                - supplier_country
                                - supplier_country_code
                                - product_description
                                - weight_kg
                                - container_count
                                - quantity
                                - quantity_unit
                                - route
                                - hs_code
                                - port_of_loading
                                - port_of_discharge
                              additionalProperties: false
                            maxItems: 50
                          matches:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                url:
                                  type: string
                                country_code:
                                  type:
                                    - string
                                    - 'null'
                                address:
                                  type:
                                    - string
                                    - 'null'
                                total_shipments:
                                  type: integer
                                  minimum: 0
                                last_shipment_date:
                                  type: string
                                  format: date
                                source_rank:
                                  type: integer
                                  minimum: 0
                                selected:
                                  type: boolean
                              required:
                                - name
                                - url
                                - country_code
                                - address
                                - total_shipments
                                - last_shipment_date
                                - source_rank
                                - selected
                              additionalProperties: false
                            maxItems: 50
                          selection:
                            type: string
                            enum:
                              - name_match
                              - partial_match
                              - largest_search_hit
                          search_window:
                            type: object
                            properties:
                              limit:
                                type: integer
                                const: 50
                              returned_count:
                                type: integer
                                minimum: 0
                              capped:
                                type: boolean
                              complete:
                                type: boolean
                                const: false
                            required:
                              - limit
                              - returned_count
                              - capped
                              - complete
                            additionalProperties: false
                          returned_count:
                            type: integer
                            minimum: 0
                          source_updated_label:
                            type:
                              - string
                              - 'null'
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - company
                          - top_suppliers
                          - hs_codes
                          - recent_shipments
                          - matches
                          - selection
                          - search_window
                          - returned_count
                          - source_updated_label
                          - source
                          - coverage_note
                        additionalProperties: false
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.