API Documentation

GET /companies

Search and retrieve companies with filtering and pagination.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
page_size	integer	No	Results per page (default: 10, max: 100)
company_name	string	No	Filter by company name (partial match)
industry	string	No	Filter by industry
country	string	No	Filter by country
min_employees	integer	No	Minimum employee count
max_employees	integer	No	Maximum employee count

Example Request

GET /api/v1/companies?company_name=Apple&page=1&page_size=10

Example Response

{
  "companies": [
    {
      "company_id": "da35b9f7091c36b82a2e9bc4660eb883",
      "company_name": "APPLE",
      "ticker": "AAPL",
      "fortune_rank": 3,
      "domain": "Technology",
      "industry": "Computers, Office Equipment",
      "country": "U.S.",
      "headquarters_city": "Cupertino",
      "headquarters_state": "California",
      "ceo": "Timothy D. Cook",
      "website": "https://www.apple.com",
      "founded_year": 1976,
      "employee_count": 161000,
      "revenue": 383285000000.0,
      "market_cap_updated_m": 3594309.0,
      "revenue_percent_change": -2.8,
      "profits_m": 96995.0,
      "assets_m": 352583.0,
      "source_system": "kaggle: https://www.kaggle.com/datasets/jeannicolasduval/2024-fortune-1000-companies",
      "last_updated_at": "2024-08-05T00:00:00-07:00"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 10
}

GET /companies/{company_id}

Get a specific company by ID.

Path Parameters

Parameter	Type	Description
company_id	string	Company identifier (MD5 hash)

Example Request

GET /api/v1/companies/da35b9f7091c36b82a2e9bc4660eb883

GET /statistics

Get dataset statistics and distributions.

Example Response

{
  "total_companies": 1000,
  "total_countries": 1,
  "total_industries": 75,
  "companies_with_fortune_rank": 1000,
  "companies_with_founded_year": 981,
  "companies_with_revenue": 1000,
  "avg_employee_count": 36611.758,
  "countries": {
    "U.S.": 1000
  },
  "industries": {
    "Commercial Banks": 37,
    "Utilities: Gas and Electric": 35,
    "Mining, Crude-Oil Production": 30,
    "Specialty Retailers: Other": 28,
    "Internet Services and Retailing": 28,
    "Industrial Machinery": 28,
    "Real estate": 27,
    "Chemicals": 26,
    "Semiconductors and Other Electronic Components": 26,
    "Insurance: Property and Casualty (Stock)": 24
  }
}

GET /industries

Get list of all unique industries.

Example Response

["Technology", "Financials", "Health Care", "Industrials", "Energy"]

GET /countries

Get list of all unique countries.

Example Response

["U.S."]