Tags API Endpoint Documentation

Table of contents

Introduction

This endpoint provides access to the role taxonomy used in job classification.
Each tag belongs to one of three role levels:

• 1 = ROLE1 (broad role family)
• 2 = ROLE2 (more specific role category)
• 3 = ROLE3 (high-resolution role label)

Tags include a recursively nested parent chain, so you can traverse from a ROLE3 tag up to ROLE2 and ROLE1 in one response.

Endpoint Overview

Endpoint (list): /api/tags/
Endpoint (single element): /api/tags/{id}/
Method: GET
Authorization Required: Yes
Description: Returns role tags with optional filtering by type, name, and parent relationship.

Access Requirements

This endpoint requires an API key with access pro+ subscription. Requests without pro+ access return a permission error.

Request

Using curl

curl -X GET "https://jobdataapi.com/api/tags/?tag_type=3&name=engineer" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Using Python

import requests

url = "https://jobdataapi.com/api/tags/"
params = {
    "tag_type": "3",
    "name": "engineer"
}
headers = {"Authorization": "Api-Key YOUR_API_KEY"}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Parameters

The Tags endpoint supports the following query parameters:

• tag_type [mc]: Filter by tag level. Accepted values: 1, 2, 3, or aliases like ROLE1, ROLE2, ROLE3. Supports multi-value include/exclude syntax.
• name [mk]: Case-insensitive name search (icontains). Supports multi-keyword include/exclude syntax.
• parent_id [mi]: Filter by direct parent tag ID. Supports multi-value include/exclude syntax.
• min_jobs: Filters tags by the minimum number of related jobs.
• max_jobs: Filters tags by the maximum number of related jobs.
• min_children: Filters tags by the minimum number of direct child tags.
• max_children: Filters tags by the maximum number of direct child tags.
• page: Page number in paginated result set.
• page_size: Results per page (default and limits follow global API pagination behavior).

Multi-value behavior

This endpoint follows the same multi-value conventions used in other API endpoints:

• Pipe-separated include values: value1|value2
• Exclude values with -: -value3
• Mixed include/exclude is supported.

Examples:

• tag_type=2|3
• tag_type=ROLE3|-ROLE1
• parent_id=12|34|-56
• name=engineer|developer|-intern

Response

The response is paginated and contains tags in results.

Top-Level Response Structure

• count: Total number of matching tags.
• next: URL for next page, or null.
• previous: URL for previous page, or null.
• results: Array of tag objects.

Tag Object Structure

Each tag object includes:

• id: Unique tag identifier.
• tag_type: Role level (1, 2, 3).
• name: Canonical tag name.
• parent: Parent tag object or null.
• num_jobs: The number of job listings currently associated with the tag.
• num_children: The number of direct child tags linked to the tag.

parent is recursively nested through all available ancestors:

• ROLE3 -> parent ROLE2 -> parent ROLE1 -> null
• ROLE2 -> parent ROLE1 -> null
• ROLE1 -> null

Example Response

{
  "count": 234,
  "next": "https://jobdataapi.com/api/tags/?page=2",
  "previous": null,
  "results": [
    {
      "id": 101,
      "tag_type": 1,
      "name": "Engineer",
      "parent": null,
      "num_children": 24,
      "num_jobs": 18342
    },
    {
      "id": 245,
      "tag_type": 2,
      "name": "Data Engineer",
      "parent": {
        "id": 101,
        "tag_type": 1,
        "name": "Engineer",
        "parent": null
      },
      "num_children": 7,
      "num_jobs": 2911
    }
  ]
}

Role Tag Methodology

Our role tags are generated with a production taxonomy pipeline designed for high consistency across very large, multilingual job datasets.

Classification approach (high level)

For each job title, we run a staged classification flow:

1. Normalization first
   We normalize noisy title text before classification (e.g. remove schedule/modality/urgency/date noise, expand common abbreviations, standardize casing and punctuation).
2. Deterministic cache reuse
   Canonicalized title variants are matched against previously classified equivalents to maximize consistency and reduce drift.
3. LLM role extraction + strict post-processing
   New/unknown titles are classified into a 3-level role taxonomy and then validated/normalized with deterministic rules.

Taxonomy shape

• ROLE1 (tag_type = 1): broad occupation family (person/profession level)
• ROLE2 (tag_type = 2): reusable functional specialization
• ROLE3 (tag_type = 3): high-resolution role label

Parent links form the hierarchy: - ROLE3 -> parent ROLE2 - ROLE2 -> parent ROLE1 - ROLE1 -> null

What we intentionally optimize for

• Cross-company consistency over one-off title fidelity
• Searchability and grouping quality over literal string preservation
• Multilingual coverage with standardized English output tags
• Stable taxonomy behavior suitable for analytics, matching, and filtering

What to expect in practice

• Some jobs may only receive partial depth (e.g. ROLE1 only, or ROLE1+ROLE2) when deeper confidence is low.
• ROLE2/ROLE3 may include limited variant terms on jobs for recall (while remaining normalized role tags).
• Role tags are additive metadata for discovery/segmentation, not a legal or contractual title source.
• A job can include one primary ROLE1 and additional normalized ROLE1 tags to improve recall in role-based filtering/search.

Role tags are best if you need structured job-role intelligence at scale, rather than raw-title-only workflows.

Best-fit scenarios

• Job search and recommendation systems
  Improve recall/precision with role-based filters (role1_id, role2_id, role3_id) and normalized role groupings.
• Market and labor analytics
  Track demand by broad family vs specialization without manually curating title synonyms.
• Matching and routing workflows
  Use role hierarchy as a stable feature for candidate-job matching, alerting, scoring, and segmentation.
• Data normalization pipelines
  Map heterogeneous ATS/company title conventions into a reusable English taxonomy layer.

Less ideal scenarios

• You need strict preservation of original title wording only.
• You require guaranteed full 3-level assignment for every single job regardless of confidence.
• You need role labels to reflect internal company-specific leveling conventions exactly.

Notes

• This endpoint is still in an experimental phase - job classification results and precision may vary.
• Tag hierarchy is represented via parent; children are not included in this endpoint response.
• Use /api/tags/ to discover taxonomy IDs, then apply them in /api/jobs/ filters via tag_id.
• Validate fit on your own domain slice first (industry, geography, language mix), then scale out.
• Use /api/jobs/ with role filters (tag_id, role1_id, role2_id, role3_id) for targeting.
• For best performance in job queries, only request tags=true when you need nested tag output.

Related Docs