# Beta Output Fields

These fields are **in beta**. They are opt-in, excluded from responses by default, and their shape or availability may change without notice. Please give them a try, and [let us know](/contact) what works.

## Enabling beta fields

Set `include_beta=true` on your request. When omitted (the default), none of the fields below are returned at all - not as `null`, they are simply absent from the payload.

```
GET /active-ats?time_frame=24h&include_beta=true
```

`include_beta` is available on [`active-ats`](/api/new-jobs#ats-jobs), [`active-jb`](/api/new-jobs#job-board-jobs), and [`modified-ats`](/api/modified-jobs#modified-ats-jobs).

| Field group | `active-ats` / `modified-ats` | `active-jb` |
| --- | :---: | :---: |
| Classifications (`classification_*`) | ✅ | — |
| Structured locations (`locations_derived_structured`) | ✅ | ✅ |

The classification fields are **ATS-only**. The structured location breakdown is available on **both** feeds.

## Classifications

Each classification field is a single JSON object (or `null` when the job could not be classified). Skills are the exception - a JSON array of objects, since a job maps to many skills.

The standardized taxonomies (`classification_isco`, `classification_onet`, `classification_soc`) carry an `id` and a human-readable `name`. The Lightcast fields additionally carry a `confidence` score between 0 and 1.

| Field | Shape | Description |
| --- | --- | --- |
| `classification_isco` | `{ id, name }` | [ISCO-08](https://ilostat.ilo.org/methods/concepts-and-definitions/classification-occupation/) occupation classification. |
| `classification_onet` | `{ id, name }` | [O*NET-SOC](https://www.onetcenter.org/taxonomy.html) occupation classification. |
| `classification_soc` | `{ id, name }` | [SOC](https://www.bls.gov/soc/) occupation classification. |
| `classification_lightcast_occupation` | `{ id, name, confidence }` | Occupation from the [Lightcast Occupation Taxonomy (LOT)](https://lightcast.io/lot/occupations/categories). |
| `classification_lightcast_title` | `{ id, name, confidence }` | Normalized job title from [Lightcast Titles](https://lightcast.io/products/data/our-taxonomies). |
| `classification_lightcast_skills` | `[ { id, name, confidence }, … ]` | Skills detected in the listing, from the [Lightcast Open Skills taxonomy](https://lightcast.io/open-skills). |

### Example

```json
{
  "classification_isco": { "id": "2512", "name": "Software developers" },
  "classification_onet": { "id": "15-1252.00", "name": "Software Developers" },
  "classification_soc": { "id": "15-1252", "name": "Software Developers" },
  "classification_lightcast_occupation": {
    "id": "15-1252.00",
    "name": "Software Developers",
    "confidence": 0.94
  },
  "classification_lightcast_title": {
    "id": "ET68343285D9A9BC3B",
    "name": "Backend Engineer",
    "confidence": 0.88
  },
  "classification_lightcast_skills": [
    { "id": "KS1200771D9CR9LB4MWW", "name": "Python", "confidence": 0.91 },
    { "id": "KS440W865GC4VRp5NNZ7", "name": "PostgreSQL", "confidence": 0.72 }
  ]
}
```

## Structured locations

`locations_derived_structured` is a geocoded, structured breakdown of a job's locations, powered by [geocode.earth](https://geocode.earth/) (built on the open-source [Pelias](https://pelias.io/) geocoder and the [Who's on First](https://whosonfirst.org/) gazetteer). It is the object-per-location counterpart to the `locations_derived` strings: an array with one entry per resolved location.

We intend to replace the current version of locations_derived with the data from locations_derived_structured. 
The current version of locations_derived is powered by [Geoapify](https://www.geoapify.com/)

Each entry carries the point coordinates (`lat`, `lon`) plus every administrative level Pelias could resolve, ordered from the most granular (locality) to the least (continent). Each administrative level is represented by up to three keys:

- `<level>` - the name (e.g. `"Lagos"`).
- `<level>_a` - the abbreviation, where one exists (e.g. `region_a` = `"LA"`). Most localities and counties have no standard abbreviation, so this is frequently `null`.
- `<level>_gid` - the geocode.earth / Who's on First identifier for that place.

`country` additionally carries `country_code`, the ISO 3166-1 alpha-2 code (e.g. `"NG"`), alongside `country_a`, the alpha-3 code (e.g. `"NGA"`).

Any level the geocoder could not resolve for a given point is returned as `null`. Fields are always present in the object (fixed shape) so you can rely on the key set.

### Administrative levels

| Level | Keys | Meaning |
| --- | --- | --- |
| — | `lat`, `lon` | Point coordinates. |
| Locality | `locality`, `locality_a`, `locality_gid` | City / town. |
| Local admin | `localadmin`, `localadmin_a`, `localadmin_gid` | Local administrative area (below county, above locality). |
| County | `county`, `county_a`, `county_gid` | County or equivalent. |
| Macrocounty | `macrocounty`, `macrocounty_a`, `macrocounty_gid` | Grouping of counties, where used. |
| Region | `region`, `region_a`, `region_gid` | State / province / region. |
| Macroregion | `macroregion`, `macroregion_a`, `macroregion_gid` | Grouping of regions, where used. |
| Dependency | `dependency`, `dependency_a`, `dependency_gid` | Dependent or associated territory. |
| Country | `country`, `country_a`, `country_code`, `country_gid` | Country. |
| Continent | `continent`, `continent_gid` | Continent. |

For details on each placetype, see the [Pelias / Who's on First placetype documentation](https://github.com/whosonfirst/whosonfirst-placetypes).

### Example

```json
"locations_derived_structured": [
  {
    "lat": 6.447048,
    "lon": 3.344747,
    "locality": "Lagos",
    "locality_a": null,
    "locality_gid": 890437281,
    "localadmin": null,
    "localadmin_a": null,
    "localadmin_gid": null,
    "county": "Ajeromi-Ifelodun",
    "county_a": null,
    "county_gid": 1108562957,
    "macrocounty": null,
    "macrocounty_a": null,
    "macrocounty_gid": null,
    "region": "Lagos",
    "region_a": "LA",
    "region_gid": 85675343,
    "macroregion": null,
    "macroregion_a": null,
    "macroregion_gid": null,
    "dependency": null,
    "dependency_a": null,
    "dependency_gid": null,
    "country": "Nigeria",
    "country_a": "NGA",
    "country_code": "NG",
    "country_gid": 85632735,
    "continent": "Africa",
    "continent_gid": 102191573
  }
]
```

> **Note:** `locations_derived_structured` is geocoded independently (via geocode.earth) from the `locations_derived` / `cities_derived` / `regions_derived` string fields (which use our primary location pipeline). The two are complementary but may not always agree entry-for-entry. See [Nuances of Location Search](/documentation/nuances-of-location-search) for how the string fields are produced.