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
    }
  ]
}

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.
• For best performance in job queries, only request tags=true when you need nested tag output.

Related Docs