---
title: "Get estimates by companies"
method: POST
path: "/top_companies"
tags: ["Data", "Internal"]
---

# Get estimates by companies

`POST /top_companies`

## Request

- Base URL: `https://comp.emsicloud.com`
- URL: `https://comp.emsicloud.com/top_companies`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.emsicloud.com/connect/token` scopes: `emsiauth`

Determines the top companies for your query by number of matching compensation observations and returns an estimate for each.

## Request body

- object
  - `titles` string[], required: One or more codes from the Emsi Title taxonomy.
  - `socs` string[], required: One or codes from the SOC occupation taxonomy.
  - `state` union: A state FIPS code or abbreviation (e.g. `16` or `"ID"` for Idaho)
    - string
    - integer
  - `msa` integer: An MSA to produce a regionalized estimate for.
  - `counties` integer[]: One or more county FIPS codes.
  - `lat` number: A latitude. Note that this must be used with `lon`.
  - `lon` number: A longitude. Note that this must be used with `lat`.
  - `keyword` string: A full-text keyword search, allows fuzzy and boolean text searches (using '+', '-', etc.).
  - `skills` string[]: Skill names from the Skills taxonomy. Note that the name needs to match exactly against the name defined by the taxonomy.
  - `skills_operator` 'Or' | 'And': Choose one of `Or`, `And`.
  - `experiences` integer[]: Years of experience. Limited to a single value for this endpoint.
  - `percentiles` number[]: What percentile(s) to include in the estimate, defaults to 10, 25, 50, 75, and 90.
  - `industries` string[]: NAICS industry codes to limit the search scope.
  - `companies` string[]: Normalized company names to limit the search scope.
  - `model` string: Advanced feature for changing the weighting model. See the `/models` endpoint.

## Response `200`

OK

- object
  - `companies` object[], required
    - `company_name` string
    - `matching_observations` integer
    - `estimate` object
      - `search_parameters` object, required
        - `keyword` string, required
        - `socs` string[], required
        - `weight_field` string, required
        - `skills` string[], required
        - `skills_operator` integer, required
        - `companies` string[], required
        - `industries` unknown[], required
          - unknown
        - `ed_levels` unknown[], required
          - unknown
        - `experiences` integer[], required
        - `percentiles` integer[], required
        - `geography` object, required
          - `type` string, required
          - `code` string, required
          - `name` string, required
          - `abbr` string, required
          - `counties` string[], required
      - `national_estimate` object, required
        - `percentiles` object[], required
          - `percentile` integer
          - `annual_salary` integer
          - `hourly_salary` integer
          - `observations` integer
          - `observations_data` integer
        - `observations` integer, required
        - `bySocInfo` object[], required
          - `soc` string
          - `weighted` integer
      - `regional_estimate` object, required
        - `percentiles` object[], required
          - `percentile` integer
          - `annual_salary` integer
          - `hourly_salary` integer
          - `observations` integer
          - `observations_data` integer
        - `observations` integer, required
        - `bySocInfo` object[], required
          - `soc` string
          - `weighted` integer
      - `national_employment` integer, required
      - `regional_employment` integer, required
      - `socs_in_estimate` object[], required
        - `soc` string
        - `name` string
        - `national_employment` integer
        - `regional_employment` integer
      - `timings` object, required
        - `agnitio_national` integer, required
        - `agnitio_regional` integer, required
        - `gis` integer, required
        - `elastic_1` integer, required
        - `elastic_2` integer, required
        - `total` integer, required

## Other responses

- `400`: Not enough data to form an estimate (unweighted)

---

[API](https://skmtc.dev/lightcast/apis/compensation-api.md) - [All operations](https://skmtc.dev/lightcast/apis/compensation-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lightcast/apis/compensation-api/revisions/ede1efdf036c?raw)