de_DE

Jobfeed API Reference

Version 3 (last update: June 1, 2016)

Introduction

The Jobfeed API provides developers with real-time access to the Jobfeed data. By making the data from the richest job database in Europe accessible with an API, Textkernel aims to promote new uses of Jobfeed's big data capabilities through the development of third party applications. The API is accessible via HTTP GET-requests and allows you to search and group jobs from Jobfeed with the possibility of filtering your result set.


Authentication

The Jobfeed API uses Basic Authentication. With each request, you need to send a Jobfeed username and password. The account you use should have the API feature enabled.

Example
$ curl --user 'username:password' https://www.jobfeed.de/api/v3/search

Searching

The /search endpoint returns a list of jobs matching your criteria.

Request

Endpoint

Method URL
GET https://www.jobfeed.de/api/v3/search?<query>

Query parameters

Parameter Type Default Description
_labels bool 1 Include (1) or omit (0) human-readable labels for field values in the result list
_language str Country-dependent Translate labels into a given language (a two-letter ISO 639-1 language code). Supported languages: en, de, fr, nl
_limit int 10 Limit the size of the result list.
_offset int 0 Skip a number of jobs from the top of the result list.
_sort str None Name of the field on which to sort the result list
_sortdir str None Direction to sort the result list: asc or desc
_fields str All fields Specify the fields of jobs to include in the result list. The value is a comma-separated list of fields.
_pretty bool 0 If 1, the JSON output is pretty-printed. Do not use this in production.
<field> Mixed None Query the API on a specific field. See Filtering below.

Response

Status Content type Content description
200 (OK) application/json A JSON object containing:
  1. total_count: the total number of results in the set
  2. results: An array of job objects

In case of error, the API returns a 4xx/5xx status code and a JSON document with the error code and description.

Filtering

Both /search and /aggregate endpoints accept additional query parameters for filtering your result set. You can specify multiple filters as <field name>=<field value>. The values you can specify depend on the field type:

  1. For boolean fields (e.g. via_intermediary) values should be 0 or 1.
  2. For integer fields, values can be integers; additionally, for fields profession and location, a value can also be a string (e.g., job title or city name) that will be automatically mapped to an integer code.
  3. For date fields, values should be in format YYYY-MM-DD
  4. For text fields, values are interpreted as full text search query (see Full text search for details).

You can use the endpoint /fields to get information about available fields, their types and possible values (see Fields).

Example /search?_pretty=1&_sort=date&_sortdir=desc&_limit=10&profession=696
Description 10 most recent jobs with the profession code 696 (Java developer)

NB: In order to improve readability we didn't URL-encode the parameters in the examples below. You must do it in your application (or build the URLs using a library that does it automatically). Otherwise the API will interpret values like now+1h as now 1h and return an error.

Multiple values for one field

You can specify multiple values for a field by adding two square brackets [] to the field name and repeating it for each value.

Example /search?profession[]=227&profession[]=4980
Description Jobs for which the profession code is either 227 or 4980

Filtering by (non) existence

You can filter the results by presense/absense of a field using either _exists or _not_exists as a value for that field. E.g., in order to exclude expired jobs (i.e. select only active jobs), you can use expiration_date=_not_exists.

Filtering by location radius

When filtering results by geographic location, you can append __radius to the location field (note the two underscores). As value, you should provide either a city name, a postal code, or geographical coordinates (in format latitude,longitude in degrees), and append the radius in kilometers. Examples:

  • /search?location__radius=Amsterdam__25
  • /search?location__radius=1000__25
  • /search?location__radius=52.08,4.32__10

You cannot use __radius together with __range for the same field.

Filtering on a range

The suffix __range allows you to filter a field on a range of values. If using this suffix, the value format should be from__to. To make the range open-ended, you can omit either from or to.

Example /search?education_level__range=3__8
Description Jobs with education levels between 3 and 8 (inclusive)

For date ranges, as values for from and to you can use:

  • specific dates, such as 2016-03-01
  • a special value now: the current date
  • relative expressions that consist of an anchor date and an interval. An anchor date can be either now or a specific date suffixed with ||. For example:
    • now-1M: one month ago
    • now-1y-6M: one year and six months ago
    • 2016-03-01||+1w: one week after March 1st, 2016.

Supported units for date intervals are (case-sensitive):

  • y (year)
  • M (month)
  • w (week)
  • d (day)
Example /search?date__range=now-1y__now
Description Jobs posted in the past year (between 1 year ago and now)

You cannot use __range together with __radius for the same field.

Negative filters

You can negate any filter for a field by appending __not to the field name. E.g.: /search?education_level__not=5.

You can also negate __range and __radius filters in the same way, e.g.: /search?education_level__range__not=3__8

Full text search

For fields of type 'text' (such as job_title, organization_name, full_text, etc.; see Fields), you can use full text search operators, as described below.

Boolean expressions

You can filter on specific terms in field values:

Example /search?full_text=(transport OR auto) AND diesel AND NOT java
Phrase search

You can filter on occurence of specific phrases:

Example /search?full_text="diesel technician"
Fuzzy searches

You can search for similar words: the following will match documents containing 'color' as well as 'colour'.

Example /search?full_text=colour~

You can specify an acceptable edit distance as integer after the tilde (~).

Proximity searches

You can search for words that occur close to each other. The integer after the tilde specifies the maximum number of words between the two terms:

Example /search?full_text="junior manager"~3
Wildcard searches

You can use * as wildcard character. The example below will return documents containing words starting with "auto":

Example /search?full_text=auto*

Aggregations

The /aggregate endpoint allows you to aggregate information about jobs across specific fields into buckets and compute various metrics over buckets.

Request

Endpoint

Method URL
GET https://www.jobfeed.de/api/v3/aggregate?<query>

Query parameters

Parameter Type Default Description
_group str None Field to aggregate on; required. You can specify a comma separated list to group on multiple fields (see Multi-field aggregation).
_limit int 10 Limit the size of the result list. This parameter can also be used with multi-field aggregation. It has no effect when grouping by date interval.
_sort str _value Sort the resulting list of aggregation buckets:
  • _group: sort by aggregated field values
  • _value: sort by values of the aggregation metric (e.g., counts)
_sortdir str desc Direction to sort the result list: asc or desc.
_labels bool 1 Include (1) or omit (0) human-readable labels for field values in the result list.
_language str Country-dependent Translate labels into a given language (a two-letter ISO 639-1 language code). Supported languages: en, de, fr, nl.
_metric str count Aggregation metric to compute for buckets in the result list: count, count_postings, min__FLD, max__FLD, sum__FLD, avg__FLD, median__FLD, where FLD is the name of a numeric field. By default, the number of documents in each bucket is returned. See Using metrics below.
_pretty bool 0 If 1, the JSON output is pretty-printed. Do not use this in production.
<field> Mixed None Filter jobs on specific fields in the same way as for the /search endpoint: see Filtering.

Response

Status Content type Content
200 (OK) application/json A JSON list of buckets. Each bucket consist of a list of values of all aggregation fields (_group parameter) followed by the values of the metrics for this bucket.

In case of error, the API returns a 4xx/5xx status code and a JSON document with the error code and description.

Using metrics

By default, the API returns the number of documents in every bucket (_metric=count). If the metric is specified as OPERATION__FIELD (note the two underscores), the corresponding aggregation operation is applied to the values of the field for all jobs in every bucket. E.g., _metric=median__salary will compute median salary for jobs in each bucket.

One more possible metric is count_postings: it will return counts of job postings instead of unique jobs (i.e., counting duplicate postings as well).

It is not possible to compute multiple metrics in one aggregation request, with one exception: if you specify the metric as OPERATION__FIELD,count, the result will contain both the outcome of the aggregation operation and the number of jobs in every bucket.

Grouping by date intervals

When grouping by a date-typed field (date or expiration_date), you can append an aggregation interval to the field name:

  1. __week
  2. __month
  3. __quarter
  4. __year
Example /aggregate?_group=date__quarter
Description Compute the number of jobs per quarter.

When grouping by a date interval, the _limit parameter has no effect. You can use filtering by date range to limit the result list in this case:

Example /aggregate?_group=date__quarter&date__range=2015-01-01__2015-12-31
Description Compute the number of jobs per quarter for the year 2015.

Multi-field aggregation

You can perform multi-dimensional aggregations by specifying a comma-separated list of fields in the _group parameter. Each bucket will be further split into smaller buckets for every next field in the field list.

Example /aggregate?_group=organization_industry,education_level
Description Group results by organization_industry, and then further split by education_level.

You can specify separate limits on number of results for all levels of aggregation by setting _limit to a comma-separated list of integers (in the same order as the list of fields in _group). For example, _group=organization_industry,education_level&_limit=5,3) will return the top 5 most frequent industries with, for each industry, top 3 education levels.

You can also omit limits for some levels, in which case a default of 10 is applied.

Example /aggregate?_group=organization_industry,education_level,region&_limit=5,,3
Description Group results by organization_industry, then by education_level and finally by region; use default limit 10 for education level.

Just as for single-field aggregations, when grouping by a date interval, the _limit parameter has no effect (see Grouping by date intervals).

Similar to multiple limits, you can specify multiple values for _sort and _sortdir parameters when doing multi-field aggregations. If using _metric, sorting by _value will only apply to the last aggregated field; for other fields, sorting by _value will always sort by the number of jobs in buckets, not by the actual value of _metric.

Example https://www.jobfeed.nl/api/v3/aggregate?_group=region,education_level& _metric=avg__salary&_sort=_value,_value&_sortdir=asc,desc
Description This will group the jobs by region, it will order those groups ascending by size (number of jobs in each), it will split them further by education level and will sort each education level bucket within its parent region bucket descending by average salary.

Fields

The /fields endpoint provides information about all available fields: field type, English-language description, and the list of possible values (where applicable).

Request

Endpoint

Method URL
GET https://www.jobfeed.de/api/v3/fields

Query parameters

Parameter Type Default Description
_get_all bool 0 Include information about fields that are not available for your account.
_language str Country-dependent Translate labels for possible field values into a given language (a two-letter ISO 639-1 language code). Supported languages: en, de, fr, nl.
_pretty bool 0 If 1, the JSON output is pretty-printed. Do not use this in production.

Response

Status Content type Content
200 (OK) application/json A JSON object with metadata for every field: type, description and possible_values (where applicable)
Example https://www.jobfeed.de/api/v3/fields?_pretty=1&_language=en