API Technical Specs
Getting Started
Data Enrichment
The Data Enrichment APIs provide various functionalities around Sovren's knowledge base of professions and skills. The API can be used to:
- Extract and normalize skills from any HR-related text to pre-populate skill profiles.
- Improve analytics by standardizing skill and job data to Sovren's comprehensive, cross-lingual taxonomies.
- Import Sovren's taxonomies of skills and professions in your organization's tools and processes.
- Create smart matching solutions by leveraging Sovren's extensive knowledge base on synonyms and profession-skill relations.
- Automatically enrich job architectures and job catalogues with suggestions of relevant skills.
- Generate skill-based recommendations of (non-obvious) job transitions.
- Understand the skill gap between two professions, or between a current skill set and an aspired next role.
- Extract skills from training descriptions, and leverage those for targeted upskilling recommendations.
Skills API
Has the following functionality:
- extract skills from any text
- normalize skill descriptions to Sovren's V2 Skills Taxonomy
- autocomplete user input to skills in the taxonomy
- export the structure of the taxonomy
- translate skills between any of the supported languages
Professions API
Has the following functionality:
- normalize job titles to Sovren's Professions Taxonomy, and to external standards such as O*NET and ISCO
- autocomplete user input to professions in the taxonomy
- export the structure of the taxonomy
- translate professions between any of the supported languages
Ontology API
Has the following functionality:
- suggest relevant skills for a given a profession
- suggest relevant professions for a given a skill set
- infer the skill gap between two professions, or between a skill set and a profession
Rate Limits
Unlike Sovren's other APIs, the Data Enrichment APIs are rate-limited on a number-of-requests-per-time-period basis. This means that any given second/minute/hour you are allowed to have N requests. Any requests after the limit of N is reached are rejected until the time period elapses and you are allowed to have N more requests for the next time period. The specific values for each endpoint are provided below:
Endpoint | Request Limit | Time Period |
---|---|---|
POST /v10/skills/extract | 8 | 1 second |
POST /v10/skills/normalize | 16 | 1 second |
POST /v10/professions/normalize | 13 | 1 second |
POST /v10/*/autocomplete | 16 | 1 second |
POST /v10/*/lookup | 16 | 1 second |
GET /v10/*/taxonomy | 10 | 1 hour |
GET /v10/*/metadata | 10 | 1 hour |
POST /v10/ontology/* | 16 | 1 second |
Skills
Sovren's Skills API provides various ways to interact with the Skills Taxonomy:
- Extract and normalize skills from any provided text
- Autocomplete to skills in the taxonomy
- Download the full skills taxonomy (synonyms excluded)
- Lookup translations of a skill
Supported Languages
These are the supported languages, their coverage level and the corresponding ISO code for API requests/responses.
Language | Tier | ISO Code |
---|---|---|
Dutch | 1 | nl |
English | 1 | en |
French | 1 | fr |
German | 1 | de |
Italian | 1 | it |
Spanish | 1 | es |
Portuguese | 2 | pt |
Chinese (Simplified) | 3 | zh |
Chinese (Traditional) | 3 | zh_TW |
Croatian | 3 | hr |
Czech | 3 | cs |
Danish | 3 | da |
Finnish | 3 | fi |
Greek | 3 | el |
Hebrew | 3 | he |
Hungarian | 3 | hu |
Japanese | 3 | ja |
Norwegian | 3 | no |
Polish | 3 | pl |
Romanian | 3 | ro |
Russian | 3 | ru |
Slovak | 3 | sk |
Slovenian | 3 | sl |
Swedish | 3 | sv |
Turkish | 3 | tr |
Coverage Per Tier
Tier | Language Skills | IT Skills | Professional and Soft Skills |
---|---|---|---|
1 | Full | Full | Full |
2 | Full | High | High |
3 | Full | High | Basic |
Full means all skills have a translation and the coverage of synonyms is extensive.
High means all common skills have a translation and the most common synonyms are covered.
Basic means all common skills have a translation and the coverage of synonyms is lower than the other tiers.
Context validation is only applied for Tier 1 languages.
About the Skills Taxonomy
Definition of a Skill
Skills are defined broadly as any kind of capability, knowledge or behavior that contributes directly to professional performance.
Structure of the Skills Taxonomy
The taxonomy has three layers: categories, skills and synonyms/variations.
The categories layer represents the following distinction:
- Professional skills include professional activities, techniques, tools, as well as areas of knowledge and specializations.
- IT skills include programming languages as wel as software tooling.
- Soft skills include personality traits and behaviors relevant to professional performance.
- Languages are simply knowledge of individual languages.
The skills layer represents skill 'concepts', each of which has an ID and a translation in the supported languages (see the Translations section below for details). This layer is language-independent; it contains the skills themselves, not the various terms and phrases through which they are described.
The synonyms/variations layer contains the various terms and phrases that can be used to denote a skill in a given language. This layer is language-specific. Each skill is linked to one or more synonyms in each of the supported languages.
Concept Granularity and Concise Descriptions
The taxonomy is designed for usage in natural language processing software. It therefore contains concise skill descriptions (usually 1-3 words), which are likely to match skill descriptions in CVs and vacancies. For the same reason, the taxonomy contains skills with various levels of granularity (e.g. both Finance
and Real Estate Finance
). Skill descriptions are generally noun phrases, as treating all activities related to an area of expertise as separate skills would introduce too much granularity. So instead of distinguishing three separate skills for Running/Training/Tuning Machine Learning Models
, there is just a single skill called Machine Learning
. Similarly, to keep the descriptions concise, prefixes like Working with
or Expertise in
are omitted. So Working with Gas Pipelines
simply becomes Gas Pipelines
.
Translations
All skills have descriptions in Tier 1 languages, except those that represent country-specific certifications (US-only).
Taxonomy Updates
The taxonomy is updated four times per year: March, June, September and December. There might be patch releases in between, but these will only concern the synonym-level, so the structure of the taxonomy won't be affected.
Professions
Sovren's Professions API helps organizing job data according to established, international taxonomies of professions. It deals with spelling variations, synonyms and noise removal. Thus, it enables reliable analytics and effective matching of people and jobs.
Purposes of Job Title Normalization
Normalizing job title data to a taxonomy makes it possible to:
- Correlate talent data from different sources and different languages
- Reliably compare data from different sources, for instance your talent pool versus market demand
- Match people and jobs based on a standard vocabulary, thereby increasing conversion
Supported Taxonomies
Job titles can be mapped onto the following taxonomies:
- Sovren's Profession Normalization Taxonomy (an established, cross-lingual, data-driven taxonomy)
- ISCO-2008
- KLDB-2020
- ONET-2019
- (Deprecated) ONET-2010
- UK-SOC-2010
- UWV-BOC
Supported Languages
These are the supported languages for the Professions API and their corresponding ISO code for use in API requests/responses.
Language | ISO Codes for API Input | ISO Codes for API Output (OutputLanguage request parameter) |
---|---|---|
English | en | en , en_US , en_GB |
German | de | de |
Spanish | es | es |
French | fr | fr |
Italian | it | it |
Japanese | ja | ja |
Dutch | nl | nl |
Polish | pl | pl |
Portuguese | pt | pt , pt_BR , pt_PT |
Chinese | zh | zh |
Ontology
The Ontology API provides insights into the relations of objects from our Sovren's knowledge graph, in particular professions and skills. It works in combination with Sovren's Professions API and Skills API, which provide functionalities around extraction, normalization and autocompletion for profession and skill data. The endpoints of the Ontology API operate on the level of IDs; they do not return the descriptions of professions and skills. To translate IDs into descriptions, and vice versa, the Professions API and Skills API can be used.
Supported Languages
The Ontology API is language agnostic. The language support is therefore limited to those languages that are supported by both the Skills API and Professions APIs. These are currently:
- English
- French
- German
- Dutch
- Spanish
- Italian
- Portuguese
- Polish
- Japanese
- Chinese