# Kirchner Data — API guide for AI assistants
# https://www.kirchnerdata.com/llms.txt
#
# Read this file first. It contains everything needed to query US import data.
# OpenAPI machine spec: https://www.kirchnerdata.com/openapi.json
#
# Base URL: https://www.kirchnerdata.com
# Data: US ocean import Bills of Lading (2014–present)
# Auth: none required. Rate limit: 500 requests per IP per day.
#
# Always call /api/... JSON endpoints. Do not scrape HTML pages.

================================================================================
START HERE — copy a URL below exactly, then change only the keyword if needed
================================================================================

## Best option: importers + full company profiles in ONE request

GET https://www.kirchnerdata.com/api/lead-finder?keywords=skateboard+decks&match=product_desc&year=2025&include_profiles=1

- Change keywords= to your product search (spaces as + or %20).
- year= must be a four-digit year (2024 or 2025 work).
- month= is optional; defaults to full when year is set.
- Response includes importers[] (ranked list) AND profiles[] (full analysis per company).
- Use this for bulk export / Excel — do NOT call company-profile separately.

## Find importers only (no full profiles)

GET https://www.kirchnerdata.com/api/lead-finder?keywords=skateboard+decks&match=product_desc&year=2025

Each row in importers[] includes:
  name              — exact company name (use this verbatim)
  api_profile_url   — full absolute URL (copy verbatim for web_fetch; path-based /api/company-profile/{name}/{year}/{year})
  profile_url       — human HTML page only (NOT the JSON API — do not fetch this for data)

## One company profile (only after lead-finder, or use include_profiles=1 instead)

Option A — copy api_profile_url from lead-finder JSON exactly (preferred, path-based URL):

GET https://www.kirchnerdata.com/api/company-profile/SIDEWALK%20DISTRIBUTION/2025/2025

Path form avoids web_fetch query-param caching. Query-string form still works:
GET https://www.kirchnerdata.com/api/company-profile?name=SIDEWALK%20DISTRIBUTION&yr_from=2025&yr_to=2025

Option B — if your client mangles GET query strings, POST JSON:

POST https://www.kirchnerdata.com/api/company-profile
Content-Type: application/json

{"name":"CRAILTAP LLC","yr_from":2025,"yr_to":2025}

Option C — pass the path from api_profile_url as a single parameter:

GET https://www.kirchnerdata.com/api/company-profile?api_profile_url=/api/company-profile/CRAILTAP%20LLC/2025/2025

IMPORTANT: Use /api/company-profile (NOT /api/importer-profile). Some AI web_fetch tools
rewrite /api/importer-profile URLs to template placeholders before the request is sent.

================================================================================
COMMON MISTAKES (read before calling company-profile)
================================================================================

- Do NOT use /api/importer-profile if your client has a cached URL template for it.
- Do NOT build company-profile URLs by hand or from memory.
- Do NOT use OpenAPI/connector template variables in the URL.
- DO copy importers[].api_profile_url exactly from a lead-finder response.
- DO use include_profiles=1 on lead-finder for bulk export (best option).
- DO use POST /api/company-profile with JSON body if GET query params fail.

The JSON "request" object in every response shows exactly what the server received.

================================================================================
API REFERENCE
================================================================================

### 1. Lead Finder — find US importers by product keyword or HS code

GET /api/lead-finder

Required:
  keywords  OR  keyword  — search phrase (e.g. skateboard+decks, bananas, coffee)
  year      — calendar year (e.g. 2025)

Optional:
  month     — full (default when year set) or 01–12
  match     — product_desc (default) or hs_code
  limit     — max results, default 50, max 200
  include_profiles — 1 to embed full profiles[] for every importer (recommended for bulk)

Returns: importers[] with rank, name, shipments, focus_pct, profile_url, api_profile_url.
With include_profiles=1: also profiles[] with suppliers, carriers, HS codes, routes, trends.

Examples:
  GET /api/lead-finder?keywords=bananas&match=product_desc&year=2024&month=full
  GET /api/lead-finder?keyword=coffee&year=2025&include_profiles=1
  GET /api/lead-finder?keywords=9403&match=hs_code&year=2024

### 2. Company Profile — full analysis for one US importer

GET /api/company-profile/{name}/{yr_from}/{yr_to} (preferred — copy api_profile_url from lead-finder)

  GET /api/company-profile/SIDEWALK%20DISTRIBUTION/2025/2025

Legacy alias (same handler): GET /api/importer-profile — avoid if web_fetch rewrites it.

POST /api/company-profile (recommended for AI — no URL template issues)

JSON body:
  {"name":"CRAILTAP LLC","yr_from":2025,"yr_to":2025}

Year param aliases still accepted: from_year, to_year, yr_from, yr_to

### 3. Product Import Trends — shipment counts by keyword over time

GET /api/product-trends?keyword=soybeans&year=2021

Required: keyword
Optional: year (adds monthly breakdown for that year)

Example:
  GET /api/product-trends?keyword=steel&year=2021

================================================================================
RECOMMENDED WORKFLOW
================================================================================

1. GET /api/lead-finder?keywords=skateboard+decks&year=2025&include_profiles=1
2. Read importers[] for the ranked list.
3. Read profiles[] for full company data (suppliers, products, carriers, etc.).
4. Check response.request — it must match the URL you intended to call.

Do not build company-profile URLs by hand. Copy api_profile_url from JSON or use include_profiles=1.