Market API

Market endpoints return labor-market signals such as top skills, software/technology terms, term demand, and remote-work context.

Use these endpoints when a product needs market context around an occupation, job workflow, skill taxonomy, dashboard, or enrichment pipeline. Common uses include labor-market dashboards, job and occupation enrichment, skill demand context, technology trend context, and remote-work context.

Complete executable examples belong in the AvelinLabs API examples repository.

Base URL: https://api.avelinlabs.com

Authentication

Requires a runtime API key:

Authorization: Bearer <runtime-api-key>

GET /api/v1/market/top

Use this endpoint to retrieve top labor-market terms by type.

Query Parameter: type

Type: string

Required: Yes

Meaning: Term type. Supported values are technology, skill, ability, knowledge, and work_activity. The public technology category is retained for API compatibility and currently includes software-oriented market terms derived from the O*NET 30.3 reference model and job-skill enrichment.

Query Parameter: scope

Type: string

Required: No

Meaning: Market aggregation scope. Supported values are active and historical; default is active.

Query Parameter: country

Type: string

Required: No

Meaning: Optional country filter where supported.

Query Parameter: limit

Type: integer

Required: No

Meaning: Number of rows to return. Supported range is 1 to 100; default is 20.

Minimal Request

GET /api/v1/market/top?type=technology&scope=active&country=US&limit=1
Authorization: Bearer <runtime-api-key>

Minimal Response

Illustrative beta response snippet:

{
  "scope": "active",
  "country": "US",
  "terms": [
    {
      "term_type": "technology",
      "term_name": "aws",
      "job_count": 88000,
      "percentage": 0.09
    }
  ]
}

See the public example response: responses/market-top.example.json.

Response Field: scope

Meaning: Market aggregation scope used for the response.

Response Field: country

Meaning: Country filter applied to the response, or null when not filtered.

Response Field: terms

Meaning: Array of top market-demand rows.

Response Field: terms[].term_type

Meaning: Term type returned in the row.

Response Field: terms[].term_name

Meaning: Skill, software/technology term, ability, knowledge area, or work activity name.

Response Field: terms[].job_count

Meaning: Number of distinct jobs represented in the selected market scope.

Response Field: terms[].percentage

Meaning: Share of distinct jobs within the selected market scope and optional country filter.

GET /api/v1/market/overview

Use this endpoint for a compact labor-market summary.

Minimal Request

GET /api/v1/market/overview
Authorization: Bearer <runtime-api-key>

Minimal Response

Illustrative beta response snippet:

{
  "scope": "active",
  "top_skills": [
    {
      "skill_name": "python",
      "job_count": 125000,
      "percentage": 0.12
    }
  ],
  "top_technologies": [
    {
      "technology_name": "aws",
      "job_count": 88000,
      "percentage": 0.09
    }
  ],
  "remote_rate": [
    {
      "country_code": "US",
      "remote_rate": 0.18
    }
  ]
}

See the public example response: responses/market-overview.example.json.

Response Field: scope

Meaning: Market aggregation scope used for the response, when included.

Response Field: top_skills

Meaning: Top skill rows.

Response Field: top_skills[].skill_name

Meaning: Skill name.

Response Field: top_skills[].job_count

Meaning: Number of jobs represented by that skill row.

Response Field: top_skills[].percentage

Meaning: Share of jobs represented by that skill row.

Response Field: top_technologies

Meaning: Top software/technology rows.

Response Field: top_technologies[].technology_name

Meaning: Software or technology term name.

Response Field: top_technologies[].job_count

Meaning: Number of jobs represented by that software/technology row.

Response Field: top_technologies[].percentage

Meaning: Share of jobs represented by that software/technology row.

Response Field: remote_rate

Meaning: Remote-work rate rows by country.

Response Field: remote_rate[].country_code

Meaning: Country code for the row.

Response Field: remote_rate[].remote_rate

Meaning: Share of jobs marked remote in that row.

Response Field: remote_rate[].remote_jobs

Meaning: Number of remote jobs represented in that row.

Response Field: remote_rate[].total_jobs

Meaning: Total jobs represented in that row.

Additional market endpoints

The public API surface also documents these market endpoints:

• GET /api/v1/market/skills/trending: trending skill growth context.
• GET /api/v1/market/technologies/trending: trending software or technology growth context.
• GET /api/v1/market/remote-rate: remote-work rate context.

These endpoints read pre-aggregated market data and should be interpreted as directional context for product dashboards, enrichment, and planning workflows. During beta, clients should tolerate additive response fields and continue to treat counts and percentages as scoped market signals rather than universal totals.

Interpretation Notes

Market fields describe observed labor-market context within the selected scope. Percentages and counts should be interpreted as directional context for the selected market, not as universal labor-market totals.

AvelinLabs uses structured occupation intelligence and labor-market signals to support classification, matching, scoring, and explanation. The current public documentation focuses on U.S. labor market signals, job-market and skill intelligence, and O*NET 30.3-grounded occupation intelligence.

For cross-endpoint guidance, read output interpretation and standard error responses.