/distributions

Calculate data distributions based around numerical job posting fields such as salary and years of experience.

`GET` /distributions

Get a list of available distribution facets.

Code Examples

curl --request GET \
  --url https://emsiservices.com/jpa/distributions \
  --header 'Authorization: Bearer <ACCESS_TOKEN>'

Response Examples

{
  "data": [
    "salary",
    "posting_duration",
    "min_years_experience",
    "max_years_experience"
  ]
}

`POST` /distributions/{distributionFacet}

Get a data distribution by percentiles or fixed interval for a selected facet.

URL Parameters

Name

Type

Description

distributionFacet

enum

The facet used as the domain of the distribution.

Example: salary

Must be one of: max_years_experience, min_years_experience, posting_duration, salary

Query Parameters

Name	Type	Description
`area_version`	enum	Specify US Area taxonomy version to use. This parameter is optional. Default: `us_area_2024_4` Must be one of: `us_area_2024_3`, `us_area_2024_4`
`soc_version`	enum	Specify SOC taxonomy version to use. This parameter is optional. Default: `soc_2021` Must be one of: `soc_2021`
`onet_version`	enum	Specify ONET taxonomy version to use. This parameter is optional. Default: `onet_2019` Must be one of: `onet_2019`
`title_version`	enum	Specify Job Title taxonomy version to use. This parameter is optional. Default: `emsi` Must be one of: `emsi`
`company_version`	enum	Specify company taxonomy version to use. This parameter is optional. Default: `emsi_company` Must be one of: `emsi_company`
`naics_version`	enum	Specify NAICS taxonomy version to use. This parameter is optional. Default: `naics_std_2022` Must be one of: `naics_std_2022`
`new_taxonomy_versions`	enum	Use new taxonomy versions. This parameter is optional. Must be one of: `true`, `false`
`area_us_version`	enum	Specify US Area taxonomy version to use. This parameter is optional. Default: `2.0.0` Must be one of: `1.0.2`, `2.0.0`
`soc_lightcast_version`	enum	Specify SOC Lightcast taxonomy version to use. This parameter is optional. Default: `2018.2021.0` Must be one of: `2018.2021.0`
`onet_standard_version`	enum	Specify ONET Standard taxonomy version to use. This parameter is optional. Default: `2019.0.0` Must be one of: `2019.0.0`
`lot_version`	enum	Specify LOT taxonomy version to use. This parameter is optional. Default: `7` Must be one of: `6`, `7`

Request Body

{
  "filter": {
    "when": "active",
    "state_name": [
      "California"
    ]
  },
  "distribution": {
    "type": "percentile",
    "options": {
      "keys": [
        25,
        50,
        75
      ]
    },
    "metrics": [
      "unique_postings",
      "duplicate_postings"
    ]
  }
}

Code Examples

curl --request POST \
  --url https://emsiservices.com/jpa/distributions/salary \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "when": "active", "state_name": [ "California" ] }, "distribution": { "type": "percentile", "options": { "keys": [ 25, 50, 75 ] }, "metrics": [ "unique_postings", "duplicate_postings" ] } }'

Response Examples

{
  "data": {
    "distribution": {
      "buckets": [
        {
          "duplicate_postings": 422706,
          "key": 25,
          "unique_postings": 126445,
          "value": 38178
        },
        {
          "duplicate_postings": 868120,
          "key": 50,
          "unique_postings": 257335,
          "value": 52000
        },
        {
          "duplicate_postings": 1231723,
          "key": 75,
          "unique_postings": 381181,
          "value": 90000
        }
      ],
      "domain": {
        "max": 500000,
        "min": 24980
      },
      "facet": "salary",
      "interval": null,
      "type": "percentile"
    },
    "totals": {
      "duplicate_postings": 3874932,
      "unique_postings": 1445428
    }
  }
}

//Your request wasn't valid (bad parameter names or values).

{
  "errors": [
    {
      "status": 400,
      "title": "Malformed Request",
      "detail": "Expected array"
    }
  ]
}

//Your request wasn't unauthorized.

{
  "errors": [
    {
      "status": 401,
      "title": "Unauthorized Request",
      "detail": "You are not authorized to access this resource."
    }
  ]
}

//The facet you requested wasn't found.

{
  "errors": [
    {
      "status": 404,
      "title": "URL not found",
      "detail": "Unrecognized facet 'foo'"
    }
  ]
}

//Your request wasn't valid (bad keyword expression).

{
  "errors": [
    {
      "status": 422,
      "title": "Invalid request content",
      "detail": "Invalid keyword search expression syntax:\n\t\"general merchandise\" OR \"apparel\" OR \"grocery\" OR\n\t                                                  ^"
    }
  ]
}