NAV
cURL Ruby Python JavaScript

Introduction

Trendence exposes parts of its architecture for integrational use, intended to fuel your custom applications and systems with data and proper exports. This system is what we call our Talent Intelligence API. These documentation pages are intended to help you getting started.

Base URL: https://api.trendence.com/v1/

API Version: 0.2.2

Authentication

To authorize, use this code:

# With Bearer Token (recommended)
curl "https://api.trendence.com/v1/talents" \
  -H "Authorization: Bearer YOUR_API_KEY"

require 'net/http'
require 'uri'

uri = URI.parse("https://api.trendence.com/v1/talents")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.trendence.com/v1/talents',
    headers=headers
)

const fetch = require('node-fetch');

fetch('https://api.trendence.com/v1/talents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

Make sure to replace YOUR_API_KEY with your actual API key.

The Trendence API uses API keys for authentication. Every request must include a valid API key.

Authentication Methods

You can provide your API key in two ways:

Send the API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

X-API-Key Header

Alternatively, you can use the X-API-Key header:

X-API-Key: YOUR_API_KEY

Content-Type Required

Otherwise, you will receive a 415 Unsupported Media Type error.

Security Recommendations

  1. Keep your API key secret: Never share your API key publicly or in version control systems.
  2. Use environment variables: Store API keys in environment variables instead of source code.
  3. Use HTTPS: All API requests are required to be made over HTTPS.
  4. Rotate keys regularly: Request a new API key when needed.

Talents

Create Talent Analysis

curl --request POST \
  --url "https://api.trendence.com/v1/talents" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "talent_text": {
      "description": "Experienced Full-Stack Developer with 5 years of professional experience. Expertise in React, Node.js, and Python."
    },
    "location": {
      "country": "DE"
    }
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://api.trendence.com/v1/talents")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "talent_text" => {
    "description" => "Experienced Full-Stack Developer with 5 years..."
  },
  "location" => {
    "country" => "DE"
  }
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

import requests
import json

url = "https://api.trendence.com/v1/talents"
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'talent_text': {
        'description': 'Experienced Full-Stack Developer with 5 years...'
    },
    'location': {
        'country': 'DE'
    }
}

response = requests.post(url, headers=headers, json=data)

const fetch = require('node-fetch');

const url = 'https://api.trendence.com/v1/talents';
const data = {
  talent_text: {
    description: 'Experienced Full-Stack Developer with 5 years...'
  },
  location: {
    country: 'DE'
  }
};

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

The above command returns JSON structured like this:

{
  "meta": {
    "tie": {
      "version": "0.2.2"
    }
  },
  "status": "pending",
  "hints": "The data is being prepared, please check talent_url for an update.",
  "talent_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "talent_url": "https://api.trendence.com/v1/talents/550e8400-e29b-41d4-a716-446655440000"
}

This endpoint creates a new asynchronous talent analysis.

HTTP Request

POST https://api.trendence.com/v1/talents

Request Body Parameters

Parameter Type Required Description
talent_text.description String Yes Description of the talent in natural language (minimum 50 characters)
language String No Language code for the analysis (e.g., "de", "en")
location.country String Yes ISO 3166-1 alpha-2 country code (e.g., "DE", "AT", "CH")
location.region String No Region name (see valid values below)
location.coordinates.lat String No Latitude coordinate
location.coordinates.lng String No Longitude coordinate

Valid Region Values:

Query Parameters

Parameter Type Default Description
force_sync Boolean false When true, processes synchronously (max. 29 seconds)

Response

The API processes requests asynchronously by default. Upon successful acceptance, you will receive a 202 Accepted response.

Get Talent Analysis

curl --request GET \
  --url "https://api.trendence.com/v1/talents/550e8400-e29b-41d4-a716-446655440000" \
  --header "Authorization: Bearer YOUR_API_KEY"

require 'net/http'
require 'uri'

uuid = "550e8400-e29b-41d4-a716-446655440000"
uri = URI.parse("https://api.trendence.com/v1/talents/#{uuid}")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

import requests

uuid = "550e8400-e29b-41d4-a716-446655440000"
url = f"https://api.trendence.com/v1/talents/{uuid}"
headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.get(url, headers=headers)

const uuid = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://api.trendence.com/v1/talents/${uuid}`;

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

When processing is complete (200 OK):

{
  "meta": {
    "tie": {
      "version": "0.2.2"
    }
  },
  "status": "completed",
  "talent_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "request": {
    "talent_text": {
      "description": "Experienced Full-Stack Developer with 5 years..."
    },
    "language": "en",
    "location": {
      "country": "DE",
      "region": "Brandenburg / Berlin"
    }
  },
  "results": [{
    "skillset_id": "12345",
    "skillset_label": "Software Development",
    "vacancies": {
      "current": [
        {
          "location": "Berlin",
          "similarity": 0.9466,
          "vacancy_url": "https://jobportal24.example/view/abc123",
          "vacancy_title": "Senior Full Stack Developer (m/f/d)",
          "organization_name": "TechCorp GmbH",
          "vacancy_publish_date": "2025-06-08"
        },
        {
          "location": "Munich",
          "similarity": 0.9234,
          "vacancy_url": "https://careersite.example/jobs/def456",
          "vacancy_title": "Full Stack Engineer",
          "organization_name": "InnovateLabs AG",
          "vacancy_publish_date": "2025-06-15"
        }
      ],
      "sources_last_12_months": [
        {"count": 45821, "share": 0.312, "source": "jobportal24.example"},
        {"count": 28934, "share": 0.197, "source": "careersite.example"},
        {"count": 19283, "share": 0.131, "source": "hiringboard.example"}
      ],
      "employers_last_12_months": [
        {"count": 342, "share": 0.089, "employer": "TechCorp GmbH"},
        {"count": 287, "share": 0.075, "employer": "InnovateLabs AG"},
        {"count": 215, "share": 0.056, "employer": "Digital Solutions GmbH"}
      ]
    },
    "labour_market": {
      "salary": {
        "q10": 52000, "q20": 58000, "q30": 63000, "q40": 68000,
        "q50": 72000, "q60": 76000, "q70": 81000, "q80": 87000, "q90": 95000
      },
      "scarcity": {
        "scarcity_index": 7.8,
        "vacancy_duration": "high",
        "campaigns_repeated": "very high",
        "job_change_reluctance": "low",
        "median_earnings_change": "high"
      },
      "vacancies_count": [
        {"date": "2025-04-01", "vacancies": 156},
        {"date": "2025-05-01", "vacancies": 178}
      ],
      "kldb_vacancies_jobseekers_ratio": [
        {"date": "2025-04-01", "vacancies": 1245, "jobseekers": 3890,
         "vacancies_jobseekers_ratio": 0.32}
      ]
    },
    "matched_profession_profile": {
      "tools": ["React", "Node.js", "Docker", "Git"],
      "hard_skills": ["JavaScript", "TypeScript", "REST APIs", "SQL"],
      "soft_skills": ["Communication", "Problem Solving"],
      "responsibilities": ["Develop web applications", "Code reviews", "Team collaboration"],
      "similar_titles": ["Full Stack Developer", "Software Engineer", "Web Developer"]
    }
  }]
}

This endpoint retrieves the status or result of a talent analysis.

The results array contains matching vacancy data including job postings, similarity scores, labour market analytics (salary, scarcity index), and statistics about vacancy sources and employers. See Understanding Talent Responses for detailed field descriptions.

HTTP Request

GET https://api.trendence.com/v1/talents/:uuid

URL Parameters

Parameter Description
uuid The UUID of the talent analysis to retrieve

Response Status Codes

Status Meaning
202 Accepted Analysis is still processing
200 OK Analysis is complete, result available
502 Bad Gateway Processing error occurred

Understanding Talent Responses

When you submit a talent description, the API performs intelligent job matching and returns four key types of information:

  1. Matching Job Vacancies - A ranked list of relevant job opportunities with similarity scores, enabling you to present the best-fitting positions to job seekers.

  2. Labour Market Analytics - Salary quantiles (q10-q90) and recruitment complexity metrics including the Recruitment Complexity Index (scarcity_index), helping candidates understand compensation expectations and their market value.

  3. Market Intelligence - Insights into where these jobs are posted (sources) and which employers are hiring, helping you understand the job market landscape.

  4. Talent Profile - Extracted skills, tools, responsibilities, and matching job titles from the talent description.

Response Structure

Field Type Description
results Array Analysis results (typically one element)
results[].vacancies Object Vacancy-related data
results[].labour_market Object Salary and recruitment complexity metrics
results[].matched_profession_profile Object Extracted skills and profile data
results[].skillset_id String Internal skillset classification ID
results[].skillset_label String Human-readable skillset label

Vacancy Fields

Field Description Usage Notes
location Geographic location Filter by candidate's preferred location
similarity Match quality (0-1) Higher values indicate better match between talent and vacancy
vacancy_url Direct link to posting Provide to candidates for easy application
vacancy_title Job position title Display prominently in your UI
organization_name Hiring organization Useful for company preference filtering
vacancy_publish_date Publication date (YYYY-MM-DD) Prioritize recent postings

Labour Market Data

Field Description Usage Notes
salary.q10 - salary.q90 Salary quantiles Annual salary in local currency; q50 is median
scarcity.scarcity_index Recruitment Complexity Index (0-10) Higher = harder to find candidates = better market value
scarcity.vacancy_duration Time to fill Values: low, high, very high
scarcity.campaigns_repeated Reposting frequency very high = candidate scarcity = strong negotiating position
scarcity.median_earnings_change Salary growth when switching jobs very high = potential for salary increases
vacancies_count[] Historical vacancy volume Monthly time series showing demand trends
kldb_vacancies_jobseekers_ratio[] Supply-demand ratio Higher ratio = tighter labor market = better prospects

Profession Profile

Field Description
tools Technical tools and platforms identified (e.g., "React", ".NET Core")
hard_skills Technical competencies detected (e.g., "Typescript", "Angular")
soft_skills Non-technical competencies
responsibilities Experience areas and capabilities
similar_titles Job titles matching the talent's profile

Polling Strategy

For asynchronous requests, we recommend using exponential backoff when polling for results.

Professions

Create Profession Analysis

curl --request POST \
  --url "https://api.trendence.com/v1/professions" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "profession_text": {
      "title": "Full Stack Developer",
      "description": "Full Stack Developer with over 10 years of experience..."
    },
    "language": "de",
    "location": {
      "country": "DE"
    }
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://api.trendence.com/v1/professions")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "profession_text" => {
    "title" => "Full Stack Developer",
    "description" => "Full Stack Developer with over 10 years..."
  },
  "language" => "de",
  "location" => {
    "country" => "DE"
  }
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

import requests

url = "https://api.trendence.com/v1/professions"
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
data = {
    'profession_text': {
        'title': 'Full Stack Developer',
        'description': 'Full Stack Developer with over 10 years...'
    },
    'language': 'de',
    'location': {
        'country': 'DE'
    }
}

response = requests.post(url, headers=headers, json=data)

const fetch = require('node-fetch');

const url = 'https://api.trendence.com/v1/professions';
const data = {
  profession_text: {
    title: 'Full Stack Developer',
    description: 'Full Stack Developer with over 10 years...'
  },
  language: 'de',
  location: {
    country: 'DE'
  }
};

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

The above command returns JSON structured like this:

{
  "meta": {
    "tie": {
      "version": "0.2.2"
    }
  },
  "status": "pending",
  "hints": "The data is being prepared, please check professions_url for an update.",
  "professions_uuid": "660e8400-e29b-41d4-a716-446655440001",
  "professions_url": "https://api.trendence.com/v1/professions/660e8400-e29b-41d4-a716-446655440001"
}

This endpoint creates a new asynchronous profession analysis.

The API supports two input methods:

HTTP Request

POST https://api.trendence.com/v1/professions

Request Body Parameters

Text-Based Request Parameters

Parameter Type Required Description
profession_text.title String Yes* Job title
profession_text.description String Yes* Description of the profession in natural language (minimum 50 characters)

*Required when using text-based approach

Taxonomy-Based Request Parameters

Parameter Type Required Description
profession_taxonomy.taxonomy String Yes* Taxonomy system identifier: "kldb" or "berufenet"
profession_taxonomy.id String Yes* Occupation code within the taxonomy (e.g., "43413" for Software Developers in KLDB)

*Required when using taxonomy-based approach

Supported Taxonomy Systems: - KLDB (Klassifikation der Berufe) - German occupation classification - BERUFENET (Berufenet) - Federal Employment Agency occupation database

Common Parameters (Both Approaches)

Parameter Type Required Description
language String No Language code for the analysis (e.g., "de", "en")
location.country String Yes ISO 3166-1 alpha-2 country code (e.g., "DE", "AT", "CH")
location.region String No Region name (see valid values in Talents section)
location.coordinates.lat String No Latitude coordinate
location.coordinates.lng String No Longitude coordinate

Valid Region Values: See the Talents section above for the complete list of valid region values.

Query Parameters

Parameter Type Default Description
force_sync Boolean false When true, processes synchronously (max. 29 seconds)

Taxonomy Code based input

Instead of providing a text description, you can use standardized occupation classification codes. This is useful when you already have classified occupation data or want to ensure consistent classification.

# Using KLDB occupation code instead of text description
curl --request POST \
  --url "https://api.trendence.com/v1/professions" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "profession_taxonomy": {
      "taxonomy": "kldb",
      "id": "43413"
    },
    "language": "de",
    "location": {
      "country": "DE",
      "region": "Brandenburg / Berlin"
    }
  }'

# Using BERUFENET occupation ID
curl --request POST \
  --url "https://api.trendence.com/v1/professions" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "profession_taxonomy": {
      "taxonomy": "berufenet",
      "id": "58965"
    },
    "language": "de",
    "location": {
      "country": "DE"
    }
  }'

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://api.trendence.com/v1/professions")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Content-Type"] = "application/json"

# Example with KLDB
request.body = JSON.dump({
  "profession_taxonomy" => {
    "taxonomy" => "kldb",
    "id" => "43413"
  },
  "language" => "de",
  "location" => {
    "country" => "DE"
  }
})

# Or with BERUFENET
# request.body = JSON.dump({
#   "profession_taxonomy" => {
#     "taxonomy" => "berufenet",
#     "id" => "58965"
#   },
#   "language" => "de",
#   "location" => {
#     "country" => "DE"
#   }
# })

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

import requests

url = "https://api.trendence.com/v1/professions"
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Example with KLDB
data = {
    'profession_taxonomy': {
        'taxonomy': 'kldb',
        'id': '43413'
    },
    'language': 'de',
    'location': {
        'country': 'DE'
    }
}

# Or with BERUFENET
# data = {
#     'profession_taxonomy': {
#         'taxonomy': 'berufenet',
#         'id': '58965'
#     },
#     'language': 'de',
#     'location': {
#         'country': 'DE'
#     }
# }

response = requests.post(url, headers=headers, json=data)

const fetch = require('node-fetch');

const url = 'https://api.trendence.com/v1/professions';

// Example with KLDB
const data = {
  profession_taxonomy: {
    taxonomy: 'kldb',
    id: '43413'
  },
  language: 'de',
  location: {
    country: 'DE'
  }
};

// Or with BERUFENET
// const data = {
//   profession_taxonomy: {
//     taxonomy: 'berufenet',
//     id: '58965'
//   },
//   language: 'de',
//   location: {
//     country: 'DE'
//   }
// };

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));

Returns the same response format as text-based requests.

Common Taxonomy Reference

Example KLDB Codes

KLDB Code Occupation (German) Occupation (English)
43413 Softwareentwickler/in Software Developers
51302 Krankenpfleger/in Nurses
62193 Verkäufer/in Sales Personnel

Example BERUFENET IDs

BERUFENET ID Occupation (German) Occupation (English)
58965 Fachinformatiker/in - Anwendungsentwicklung IT Specialist - Application Development
9162 Krankenschwester/Krankenpfleger Nurse
120735 Vertriebsassistent/in Sales Assistant

Get Profession Analysis

curl --request GET \
  --url "https://api.trendence.com/v1/professions/660e8400-e29b-41d4-a716-446655440001" \
  --header "Authorization: Bearer YOUR_API_KEY"

require 'net/http'
require 'uri'

uuid = "660e8400-e29b-41d4-a716-446655440001"
uri = URI.parse("https://api.trendence.com/v1/professions/#{uuid}")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

import requests

uuid = "660e8400-e29b-41d4-a716-446655440001"
url = f"https://api.trendence.com/v1/professions/{uuid}"
headers = {'Authorization': 'Bearer YOUR_API_KEY'}

response = requests.get(url, headers=headers)

const uuid = '660e8400-e29b-41d4-a716-446655440001';
const url = `https://api.trendence.com/v1/professions/${uuid}`;

fetch(url, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

When processing is complete (200 OK):

{
  "meta": {
    "tie": {
      "version": "0.2.2"
    }
  },
  "status": "completed",
  "professions_uuid": "660e8400-e29b-41d4-a716-446655440001",
  "request": {
    "profession_text": {
      "title": "Senior Full Stack Developer",
      "description": "Full Stack Developer with over 10 years of experience in Java, JavaScript, React, Python..."
    },
    "language": "de",
    "location": {
      "country": "DE"
    }
  },
  "results": [{
    "vacancies": {
      "current": [
        {
          "location": "München",
          "similarity": 0.9430,
          "vacancy_url": "https://talentboard.example/jobs/xyz789",
          "vacancy_title": "Senior Fullstack Developer (w/m/d)",
          "organization_name": "SoftwareHouse GmbH",
          "vacancy_publish_date": "2025-06-19"
        },
        {
          "location": "Hamburg",
          "similarity": 0.9201,
          "vacancy_url": "https://careerplatform.example/positions/ghi012",
          "vacancy_title": "Full Stack Engineer",
          "organization_name": "CloudTech AG",
          "vacancy_publish_date": "2025-06-22"
        }
      ],
      "sources_last_12_months": [
        {"count": 82341, "share": 0.245, "source": "talentboard.example"},
        {"count": 61829, "share": 0.184, "source": "careerplatform.example"},
        {"count": 43567, "share": 0.130, "source": "jobfinder.example"}
      ],
      "employers_last_12_months": [
        {"count": 428, "share": 0.112, "employer": "SoftwareHouse GmbH"},
        {"count": 356, "share": 0.093, "employer": "CloudTech AG"},
        {"count": 289, "share": 0.076, "employer": "DevOps Solutions GmbH"}
      ]
    },
    "labour_market": {
      "salary": {
        "q10": 63300, "q20": 68900, "q30": 72800, "q40": 76300,
        "q50": 79700, "q60": 83000, "q70": 86700, "q80": 91400, "q90": 100700
      },
      "scarcity": {
        "scarcity_index": 8.1,
        "vacancy_duration": "high",
        "campaigns_repeated": "very high",
        "job_change_reluctance": "very low",
        "median_earnings_change": "very high",
        "avg_postings_per_campaign": "very low",
        "foreign_employee_share_change": "very high",
        "job_adds_people_available_ratio": "high"
      },
      "vacancies_count": [
        {"date": "2025-04-01", "vacancies": 21},
        {"date": "2025-05-01", "vacancies": 20},
        {"date": "2025-06-01", "vacancies": 32}
      ],
      "kldb_vacancies_jobseekers_ratio": [
        {"date": "2025-04-01", "vacancies": 892, "jobseekers": 11821,
         "vacancies_jobseekers_ratio": 0.075, "vacancies_jobseekers_ratio_log": 0.023}
      ]
    },
    "matched_profession_profile": {
      "tools": ["React", ".NET Core", "OpenAPI", "Docker"],
      "hard_skills": ["Typescript", "Angular", "Java", "Python"],
      "soft_skills": ["Kritisches Denken", "Teamarbeit"],
      "responsibilities": ["Software entwickeln", "Benutzeroberflächen optimieren", "Code Reviews durchführen"],
      "similar_titles": ["Entwickler Fullstack", "Developer", "Software Engineer"]
    }
  }],
  "metadata": {
    "taxonomy": [{
      "kldb": {
        "id": "43413",
        "label": "Softwareentwicklung - Spezialist/in"
      },
      "berufenet": {
        "id": "58965",
        "label": "Fachinformatiker/in - Anwendungsentwicklung"
      },
      "similarity_score": 0.9245
    }],
    "extracted_attributes": {
      "tools": ["React", ".NET Core", "OpenAPI"],
      "industry": "information and communication",
      "sub_industry": "computer programming activities",
      "education": [],
      "experience": ["10 years"],
      "hard_skills": ["Java", "JavaScript", "React", "Python"],
      "soft_skills": ["teamwork", "problem solving"],
      "responsibilities": ["develop software", "maintain applications", "code review"]
    }
  }
}

This endpoint retrieves the status or result of a profession analysis.

The results array contains matching vacancy data including job postings, similarity scores, labour market analytics (salary, scarcity index), and statistics about vacancy sources and employers. See Understanding Profession Responses for detailed field descriptions.

HTTP Request

GET https://api.trendence.com/v1/professions/:uuid

URL Parameters

Parameter Description
uuid The UUID of the profession analysis to retrieve

Understanding Profession Responses

When you submit a profession description, the API analyzes the job requirements and returns four key types of information:

  1. Matching Job Vacancies - A ranked list of similar job opportunities with similarity scores, enabling you to show employers comparable positions in the market.

  2. Labour Market Analytics - Salary quantiles (q10-q90) and recruitment complexity metrics including the Recruitment Complexity Index (scarcity_index), providing insights into compensation benchmarks and hiring difficulty.

  3. Market Intelligence - Insights into where these jobs are posted (sources) and which employers are hiring for similar roles, helping you understand competitive hiring landscapes.

  4. Profession Profile - Extracted skills, tools, responsibilities, and similar job titles from the profession description.

Response Structure

Field Type Description
results Array Analysis results (typically one element)
results[].vacancies Object Vacancy-related data
results[].labour_market Object Salary and recruitment complexity metrics
results[].matched_profession_profile Object Extracted skills and profile data

Vacancy Fields

Field Description Usage Notes
location Geographic location Analyze regional hiring patterns
similarity Match quality (0-1) Higher values indicate better match between talent and vacancy
vacancy_url Direct link to posting For detailed job analysis or referrals
vacancy_title Job position title Shows market positioning of similar roles
organization_name Hiring organization Identify competitors or benchmarking
vacancy_publish_date Publication date (YYYY-MM-DD) Analyze hiring trends over time

Labour Market Data

Field Description Usage Notes
salary.q10 - salary.q90 Salary quantiles Annual salary in local currency; q50 is median. Use for compensation benchmarking
scarcity.scarcity_index Recruitment Complexity Index (0-10) Higher = greater difficulty finding candidates. Use for workforce planning
scarcity.vacancy_duration Time to fill positions Values: low, high, very high. Indicates typical hiring timeline
scarcity.campaigns_repeated Reposting frequency very high = candidate scarcity
scarcity.median_earnings_change Salary growth when changing jobs Indicates competitive pressure on compensation
scarcity.foreign_employee_share_change International recruitment trend very high = reliance on foreign talent
scarcity.job_adds_people_available_ratio Supply-demand balance Higher = more competition for talent
vacancies_count[] Historical vacancy volume Monthly time series data
kldb_vacancies_jobseekers_ratio[] Supply-demand ratio over time Based on official occupation classification (KLDB)

Profession Profile

Field Description
tools Technologies mentioned or inferred (e.g., "React", ".NET Core", "OpenAPI")
hard_skills Technical competencies required (e.g., "Typescript", "Angular")
soft_skills Non-technical competencies (e.g., "Kritisches Denken")
responsibilities Job duties and tasks (e.g., "Software entwickeln")
similar_titles Alternative titles for this profession (e.g., "Developer Full Stack")

Market Intelligence

The response includes vacancy source and employer statistics:

Vacancy Sources - Shows which job boards have the most postings for this profession type. Use to optimize job posting strategy and understand platform reach.

Vacancy Employers - Lists top hiring employers with their market share. High vacancy counts indicate strong hiring demand, useful for talent scarcity assessment.

Rate Limiting

The API is limited to 100 requests per minute for POST, PUT, and PATCH requests.

When the rate limit is exceeded, you will receive a 429 Too Many Requests status:

{
  "error": "Rate limit exceeded. Please try again later."
}

Changelog

[0.2.2] - 2026-01-20

Added

[0.2.1] - 2026-01-06

Changed

[0.2.0] - 2025-12-16

Added

Changed

[0.1.0] - 2025-12-01

Versioning Policy

Every request includes the API version shipped in the response metadata:

{
  "meta": {
    "tie": {
      "version": "0.2.2"
    }
  }
}

Version Numbering

Deprecation Policy

When endpoints or features are deprecated:

  1. Deprecated features will be announced at least 6 months before removal
  2. Deprecation notices will appear in this changelog and API responses
  3. Migration guides will be provided for breaking changes

Errors

The Trendence API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Error Code Meaning
200 OK -- Analysis completed successfully (synchronous requests).
202 Accepted -- Request accepted and processing asynchronously.
400 Bad Request -- Your request is malformed or invalid.
401 Unauthorized -- Your API key is invalid or missing.
404 Not Found -- The requested resource could not be found.
415 Unsupported Media Type -- Content-Type header must be application/json.
422 Unprocessable Entity -- Validation failed (see error details).
429 Too Many Requests -- Rate limit exceeded. Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
502 Bad Gateway -- The backend service is temporarily unavailable.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Validation Errors

When validation fails (422 status), the API returns a detailed error response:

{
  "error": "Validation failed",
  "missing_fields": [
    "profession_text or profession_taxonomy is required"
  ],
  "example": {
    "profession_text": {
      "title": "Full Stack Developer",
      "description": "Full Stack Developer with experience in Java, JavaScript, and modern web frameworks."
    },
    "profession_taxonomy": {
      "taxonomy": "kldb",
      "id": "12193"
    },
    "location": {
      "country": "DE"
    }
  },
  "meta": {
    "tie": {
      "version": "0.2.1"
    }
  }
}

Common Validation Errors

Error Message Cause Solution
profession_text or profession_taxonomy is required Neither text nor taxonomy provided Provide either profession_text with title/description OR profession_taxonomy with taxonomy/id
profession_taxonomy.id is required Taxonomy object missing id field Include both taxonomy and id fields in profession_taxonomy
location.country is required Missing country code Provide ISO 3166-1 alpha-2 country code (e.g., "DE", "AT", "CH")
talent_text.description is required Missing talent description Provide description in talent_text object

Taxonomy Not Found (404)

When using taxonomy-based requests, you may receive a 404 error if the specified occupation code is not found or unavailable:

{
  "error": "Upstream request failed",
  "detail": "Profession not found or embedding unavailable: 'berufenet:11510 not found'",
  "meta": {
    "tie": {
      "version": "0.2.1"
    }
  }
}

Common Causes

Solution

Verify that your taxonomy code is valid: - For KLDB: Check the official KLDB classification - For BERUFENET: Check the BERUFENET database

Rate Limiting

{
  "error": "Rate limit exceeded. Please try again later."
}

When you exceed the rate limit (100 requests per minute for POST/PUT/PATCH), you'll receive a 429 status code. Implement exponential backoff in your client to handle rate limiting gracefully.

cURL Ruby Python JavaScript