{
  "openapi": "3.1.0",
  "info": {
    "title": "Kirchner Data — US Import Analytics API",
    "version": "1.4.0",
    "description": "Public API for US ocean import Bills of Lading. AI: read https://www.kirchnerdata.com/llms.txt. Bulk profiles: GET /api/lead-finder?include_profiles=1. Single profile: GET /api/company-profile/{name}/{yr_from}/{yr_to} or POST /api/company-profile."
  },
  "servers": [
    {
      "url": "https://www.kirchnerdata.com"
    }
  ],
  "paths": {
    "/api/product-trends": {
      "get": {
        "operationId": "getProductTrends",
        "summary": "Product import trends by keyword",
        "description": "Returns annual US import shipment counts (unique Bills of Lading) for a product keyword across 2014–2025. Optionally includes monthly breakdown for a single year. Powers the Product Import Trends tool at /econ2.",
        "parameters": [
          {
            "name": "keyword",
            "in": "query",
            "required": true,
            "description": "Product keyword searched in bill-of-lading product descriptions (e.g. soybeans, steel, bearings).",
            "schema": {
              "type": "string",
              "minLength": 1,
              "example": "soybeans"
            }
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Calendar year (2014–2025). When provided, the response includes monthly shipment counts for that year.",
            "schema": {
              "type": "integer",
              "minimum": 2014,
              "maximum": 2025,
              "example": 2021
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Import trend data for the keyword.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductTrendsResponse"
                },
                "example": {
                  "keyword": "soybeans",
                  "unit": "shipments",
                  "data_source": "US Bills of Lading",
                  "annual": {
                    "2014": 1200,
                    "2015": 1450,
                    "2016": 1380,
                    "2017": 1520,
                    "2018": 1610,
                    "2019": 1700,
                    "2020": 1550,
                    "2021": 1800,
                    "2022": 1750,
                    "2023": 1900,
                    "2024": 1850,
                    "2025": 920
                  },
                  "monthly": {
                    "2021": {
                      "Jan": 110,
                      "Feb": 95,
                      "Mar": 120,
                      "Apr": 105,
                      "May": 130,
                      "Jun": 115,
                      "Jul": 140,
                      "Aug": 125,
                      "Sep": 150,
                      "Oct": 135,
                      "Nov": 160,
                      "Dec": 125
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "keyword is required"
                }
              }
            }
          },
          "404": {
            "description": "No import data found for this keyword.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "no data found for keyword"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded or IP blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "rate limit exceeded"
                }
              }
            }
          }
        }
      }
    },
    "/api/lead-finder": {
      "get": {
        "operationId": "searchLeadFinder",
        "summary": "Find top US importers by product keyword or HS code",
        "description": "Returns US importers (consignees) ranked by matching import shipments for a keyword/HS search, year, and month or full year. Same data as /lead-finder. Each result includes profile_url and api_profile_url — call getImporterProfile with the company name for full analysis. Response includes a request object echoing parsed parameters.",
        "parameters": [
          {
            "name": "keywords",
            "in": "query",
            "required": false,
            "description": "Product phrase or HS code fragment. Repeat for OR across fields, or use commas/OR inside one value. Required unless keyword is set.",
            "schema": { "type": "string", "example": "skateboard decks" }
          },
          {
            "name": "keyword",
            "in": "query",
            "required": false,
            "description": "Alias for keywords (single phrase). Required unless keywords is set.",
            "schema": { "type": "string", "example": "skateboard decks" }
          },
          {
            "name": "match",
            "in": "query",
            "required": false,
            "description": "Search field: product_desc (default) or hs_code.",
            "schema": { "type": "string", "enum": ["product_desc", "hs_code"], "default": "product_desc" }
          },
          {
            "name": "year",
            "in": "query",
            "required": true,
            "schema": { "type": "integer", "minimum": 2014, "maximum": 2026, "example": 2024 }
          },
          {
            "name": "month",
            "in": "query",
            "required": false,
            "description": "Defaults to full when year is set. Use full for calendar year, or 01–12 for a single month.",
            "schema": {
              "type": "string",
              "enum": ["full", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12"],
              "default": "full",
              "example": "full"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max importers to return (default 50, max 200).",
            "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
          },
          {
            "name": "include_profiles",
            "in": "query",
            "required": false,
            "description": "Set to 1 to include full importer profiles for every result in profiles[] (one-call bulk export).",
            "schema": { "type": "string", "enum": ["1", "true", "yes"], "example": "1" }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked importer list.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LeadFinderResponse" },
                "example": {
                  "keywords": ["skateboard decks"],
                  "match": "product_desc",
                  "match_label": "Product description",
                  "year": 2025,
                  "month": "full",
                  "period": "Full year",
                  "unit": "shipments",
                  "data_source": "US Bills of Lading",
                  "total_matched": 20,
                  "request": {
                    "keywords": ["skateboard decks"],
                    "match": "product_desc",
                    "year": 2025,
                    "month": "full",
                    "limit": 50
                  },
                  "importers": [
                    {
                      "rank": 1,
                      "name": "SIDEWALK DISTRIBUTION",
                      "total_shipments": 5,
                      "matching_shipments": 5,
                      "focus_pct": 100,
                      "profile_url": "/importer-profile?name=SIDEWALK%20DISTRIBUTION&from_year=2025&to_year=2025",
                      "api_profile_url": "https://www.kirchnerdata.com/api/company-profile/SIDEWALK%20DISTRIBUTION/2025/2025"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid parameters.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LeadFinderErrorResponse" },
                "examples": {
                  "missingKeywords": {
                    "summary": "No keywords",
                    "value": {
                      "error": "keywords (or keyword) is required",
                      "hint": "Use keywords=your+search+terms or keyword=single+phrase (URL-encode spaces as + or %20). Example: /api/lead-finder?keywords=skateboard+decks&match=product_desc&year=2025",
                      "request": { "keywords": [], "match": "product_desc", "year": null, "month": "", "limit": 50 }
                    }
                  },
                  "invalidYear": {
                    "summary": "Year out of range",
                    "value": {
                      "error": "year is required and must be between 2014 and 2025",
                      "request": { "keywords": ["bananas"], "match": "product_desc", "year": 2030, "month": "full", "limit": 50 }
                    }
                  }
                }
              }
            }
          },
          "404": { "description": "No importers found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/api/company-profile": {
      "post": {
        "operationId": "postCompanyProfile",
        "summary": "Full US importer profile (recommended for AI)",
        "description": "Preferred method for AI clients. Send JSON body with exact name from lead-finder importers[].name. For bulk export use GET /api/lead-finder?include_profiles=1 instead.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "yr_from", "yr_to"],
                "properties": {
                  "name": { "type": "string", "example": "CRAILTAP LLC" },
                  "yr_from": { "type": "integer", "example": 2025 },
                  "yr_to": { "type": "integer", "example": 2025 },
                  "from_year": { "type": "integer", "example": 2025 },
                  "to_year": { "type": "integer", "example": 2025 }
                }
              },
              "example": { "name": "CRAILTAP LLC", "yr_from": 2025, "yr_to": 2025 }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Importer profile data.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ImporterProfileResponse" }
              }
            }
          },
          "400": {
            "description": "Missing name or invalid value.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ImporterProfileErrorResponse" }
              }
            }
          },
          "404": { "description": "No data for importer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      },
      "get": {
        "operationId": "getCompanyProfile",
        "summary": "Full US importer profile by query string",
        "description": "Fetch full importer analysis. Preferred: copy importers[].api_profile_url from lead-finder (path form /api/company-profile/{name}/{yr_from}/{yr_to}). Query-string GET also supported.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "description": "Exact US importer name from lead-finder importers[].name (URL-encoded). Example value only: SIDEWALK DISTRIBUTION",
            "schema": { "type": "string", "example": "SIDEWALK DISTRIBUTION" }
          },
          {
            "name": "yr_from",
            "in": "query",
            "required": true,
            "description": "Start year (alias: from_year).",
            "schema": { "type": "integer", "minimum": 2014, "maximum": 2026, "example": 2025 }
          },
          {
            "name": "yr_to",
            "in": "query",
            "required": true,
            "description": "End year (alias: to_year).",
            "schema": { "type": "integer", "minimum": 2014, "maximum": 2026, "example": 2025 }
          }
        ],
        "responses": {
          "200": {
            "description": "Importer profile data.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ImporterProfileResponse" },
                "example": {
                  "name": "SIDEWALK DISTRIBUTION",
                  "from_year": 2025,
                  "to_year": 2025,
                  "total_shipments": 5,
                  "unit": "shipments",
                  "data_source": "US Bills of Lading",
                  "request": {
                    "name": "SIDEWALK DISTRIBUTION",
                    "from_year": 2025,
                    "to_year": 2025
                  },
                  "api_profile_url": "https://www.kirchnerdata.com/api/company-profile/SIDEWALK%20DISTRIBUTION/2025/2025"
                }
              }
            }
          },
          "400": {
            "description": "Missing name or documentation placeholder sent instead of real values.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ImporterProfileErrorResponse" }
              }
            }
          },
          "404": { "description": "No data for importer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    },
    "/api/importer-profile": {
      "post": {
        "operationId": "postImporterProfile",
        "summary": "Full US importer profile (legacy alias)",
        "description": "Legacy alias of POST /api/company-profile. Prefer /api/company-profile for AI clients with cached URL templates.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "yr_from", "yr_to"],
                "properties": {
                  "name": { "type": "string", "example": "CRAILTAP LLC" },
                  "yr_from": { "type": "integer", "example": 2025 },
                  "yr_to": { "type": "integer", "example": 2025 },
                  "from_year": { "type": "integer", "example": 2025 },
                  "to_year": { "type": "integer", "example": 2025 }
                }
              },
              "example": { "name": "CRAILTAP LLC", "yr_from": 2025, "yr_to": 2025 }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Importer profile data.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ImporterProfileResponse" }
              }
            }
          },
          "400": {
            "description": "Missing name or invalid value.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ImporterProfileErrorResponse" }
              }
            }
          },
          "404": { "description": "No data for importer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      },
      "get": {
        "operationId": "getImporterProfile",
        "summary": "Full US importer profile by query string (legacy alias)",
        "description": "Legacy alias of GET /api/company-profile. Prefer copying importers[].api_profile_url from lead-finder (uses /api/company-profile).",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "description": "Exact US importer name from lead-finder importers[].name (URL-encoded). Example value only: SIDEWALK DISTRIBUTION",
            "schema": { "type": "string", "example": "SIDEWALK DISTRIBUTION" }
          },
          {
            "name": "yr_from",
            "in": "query",
            "required": true,
            "description": "Start year (alias: from_year). Use yr_from to avoid web_fetch URL template issues.",
            "schema": { "type": "integer", "minimum": 2014, "maximum": 2026, "example": 2025 }
          },
          {
            "name": "yr_to",
            "in": "query",
            "required": true,
            "description": "End year (alias: to_year).",
            "schema": { "type": "integer", "minimum": 2014, "maximum": 2026, "example": 2025 }
          }
        ],
        "responses": {
          "200": {
            "description": "Importer profile data.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ImporterProfileResponse" },
                "example": {
                  "name": "SIDEWALK DISTRIBUTION",
                  "from_year": 2025,
                  "to_year": 2025,
                  "total_shipments": 5,
                  "unit": "shipments",
                  "data_source": "US Bills of Lading",
                  "request": {
                    "name": "SIDEWALK DISTRIBUTION",
                    "from_year": 2025,
                    "to_year": 2025
                  },
                  "api_profile_url": "https://www.kirchnerdata.com/api/company-profile/SIDEWALK%20DISTRIBUTION/2025/2025"
                }
              }
            }
          },
          "400": {
            "description": "Missing name or documentation placeholder sent instead of real values.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ImporterProfileErrorResponse" },
                "example": {
                  "error": "name must be a real company name, not a documentation placeholder",
                  "hint": "Call GET /api/lead-finder?include_profiles=1 to fetch all profiles in one response, or pass importers[].api_profile_url as api_profile_url=.",
                  "request": {
                    "name": "LITERAL_PLACEHOLDER_NOT_A_COMPANY",
                    "from_year": 2025,
                    "to_year": 2025
                  }
                }
              }
            }
          },
          "404": { "description": "No data for importer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
          "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProductTrendsResponse": {
        "type": "object",
        "required": ["keyword", "unit", "data_source", "annual"],
        "properties": {
          "keyword": {
            "type": "string",
            "example": "soybeans"
          },
          "unit": {
            "type": "string",
            "enum": ["shipments"],
            "description": "Count of unique Bills of Lading (shipments)."
          },
          "data_source": {
            "type": "string",
            "example": "US Bills of Lading"
          },
          "annual": {
            "type": "object",
            "description": "Annual shipment counts keyed by four-digit year (2014–2025).",
            "additionalProperties": {
              "type": "integer",
              "minimum": 0
            },
            "example": {
              "2014": 1200,
              "2015": 1450,
              "2025": 920
            }
          },
          "monthly": {
            "type": "object",
            "description": "Present only when the year query parameter is provided. Monthly counts for that year.",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "integer",
                "minimum": 0
              }
            },
            "example": {
              "2021": {
                "Jan": 110,
                "Feb": 95,
                "Mar": 120,
                "Apr": 105,
                "May": 130,
                "Jun": 115,
                "Jul": 140,
                "Aug": 125,
                "Sep": 150,
                "Oct": 135,
                "Nov": 160,
                "Dec": 125
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "LeadFinderImporter": {
        "type": "object",
        "required": ["rank", "name", "total_shipments", "matching_shipments", "focus_pct", "profile_url", "api_profile_url"],
        "properties": {
          "rank": { "type": "integer" },
          "name": { "type": "string" },
          "total_shipments": { "type": "integer" },
          "matching_shipments": { "type": "integer" },
          "focus_pct": { "type": "number" },
          "two_year_growth_pct": { "type": "number" },
          "match_weight_total_kg": { "type": "number" },
          "match_weight_min_bol_kg": { "type": "number" },
          "match_weight_max_bol_kg": { "type": "number" },
          "profile_url": { "type": "string", "description": "Human-readable importer profile page." },
          "api_profile_url": { "type": "string", "description": "Full absolute URL for importer profile JSON API (copy verbatim)." }
        }
      },
      "LeadFinderErrorResponse": {
        "type": "object",
        "required": ["error", "request"],
        "properties": {
          "error": { "type": "string" },
          "hint": { "type": "string" },
          "request": { "$ref": "#/components/schemas/LeadFinderRequestEcho" }
        }
      },
      "LeadFinderRequestEcho": {
        "type": "object",
        "properties": {
          "keywords": { "type": "array", "items": { "type": "string" } },
          "match": { "type": "string" },
          "year": { "type": ["integer", "null"] },
          "month": { "type": "string" },
          "limit": { "type": "integer" }
        }
      },
      "LeadFinderResponse": {
        "type": "object",
        "required": ["keywords", "match", "year", "month", "unit", "data_source", "total_matched", "importers", "request"],
        "properties": {
          "keywords": { "type": "array", "items": { "type": "string" } },
          "match": { "type": "string" },
          "match_label": { "type": "string" },
          "year": { "type": "integer" },
          "month": { "type": "string" },
          "period": { "type": "string" },
          "unit": { "type": "string", "enum": ["shipments"] },
          "data_source": { "type": "string" },
          "total_matched": { "type": "integer" },
          "request": { "$ref": "#/components/schemas/LeadFinderRequestEcho" },
          "importers": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/LeadFinderImporter" }
          }
        }
      },
      "ImporterProfileRequestEcho": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "from_year": { "type": "integer" },
          "to_year": { "type": "integer" }
        }
      },
      "ImporterProfileErrorResponse": {
        "type": "object",
        "required": ["error", "request"],
        "properties": {
          "error": { "type": "string" },
          "hint": { "type": "string" },
          "request": { "$ref": "#/components/schemas/ImporterProfileRequestEcho" }
        }
      },
      "ImporterProfileResponse": {
        "type": "object",
        "required": ["name", "from_year", "to_year", "total_shipments", "unit", "data_source", "request"],
        "properties": {
          "name": { "type": "string" },
          "address": { "type": "string" },
          "country": { "type": "string" },
          "from_year": { "type": "integer" },
          "to_year": { "type": "integer" },
          "profile_url": { "type": "string" },
          "api_profile_url": { "type": "string" },
          "request": { "$ref": "#/components/schemas/ImporterProfileRequestEcho" },
          "unit": { "type": "string" },
          "data_source": { "type": "string" },
          "total_shipments": { "type": "integer" },
          "unique_suppliers": { "type": "integer" },
          "unique_products": { "type": "integer" },
          "top_products": { "type": "array", "items": { "type": "object" } },
          "top_suppliers": { "type": "array", "items": { "type": "object" } },
          "top_carriers": { "type": "array", "items": { "type": "object" } },
          "top_origin_countries": { "type": "array", "items": { "type": "object" } },
          "monthly_shipments": { "type": "array", "items": { "type": "object" } },
          "yearly_shipments": { "type": "array", "items": { "type": "object" } },
          "latest_shipments": { "type": "array", "items": { "type": "object" } },
          "port_routes": { "type": "array", "items": { "type": "object" } },
          "newest_suppliers": { "type": "array", "items": { "type": "object" } },
          "fastest_growing_supplier": { "type": "object" },
          "products_by_country_exporter": { "type": "array", "items": { "type": "object" } }
        }
      }
    }
  }
}