de_DE

Jobfeed API Reference

Version 3 (last update: May 4, 2017)

Introduction

The Jobfeed API provides developers with real-time access to the Jobfeed data. With this 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 or POST requests and allows you to filter and aggregate jobs from Jobfeed.

The POST requests currently only support URL-encoded parameters (Content-Type: application/x-www-form-urlencoded).


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 BODY
GET https://www.jobfeed.de/api/v3/search?<query>
POST 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(s) on which to sort the result.
_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.
_snippets bool 0 When searching in the full_text field, return highlighted portions of the text that matched the search.
_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.

You can specify multiple fields for _sort using a comma-separated sequence, in which case the _sortdir will correspond to the fields in the same order as specified in _sort.

Example /search?_sort=date,organization_name&_sortdir=desc,asc
Description This will order the results by date in descending order, and results on the same date by organisation_name in ascending order.

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 prefix

For string fields, you can filter results by prefixed search appending __prefix to the field.

Example /search?source_website__prefix=example
Description Jobs for which the source website begins with example, i.e. examplejobboards.com, examplevacancy.com

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 Jobfeed-specific municipality id, 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.

Filtering on a calendar period

The suffix __calendar allows you to filter a date field on complete calendar periods. The value will be the amount of periods suffixed by a unit.

Supported units:

  • m (month)
  • q (quarter)
  • y (year)
Example /search?date__calendar=2m
Description Jobs posted within the last 2 complete calendar months

Assuming today is the 11th of January 2017 2m denotes the interval between the 1st of November 2016 and the 31st of December 2016.

Filtering on custom categories

If you've defined custom categories in Jobfeed you can search by custom category IDs by suffixing the field name with __custom.

Example /search?profession__custom=123
Description Search for jobs with the profession in custom category 123

You can get the IDs of the custom categories for the fields that have support for them from the /fields endpoint.

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, __radius, __calendar and __custom 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
Example /search?full_text=(transport|auto) diesel -java

Note: The dash symbol - is sensitive to spaces; it should be placed after a space or at the beginning of the query, and should not be followed by any spaces.

Phrase search

You can filter on occurence of specific phrases by enclosing them in double double-quotes ":

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*

Using * can make queries significantly slower (up to 5 times), especially if * does not follow a prefix of at least 2 word characters. For example, query dev* will be fast, but queries *ologist or p*diatric can be up to 5 times slower.

Exact match on text fields

Two text fields (job_title and organization_name) also allow for exact string match on top of the regular full-text search:

Example /search?organization_name__exact=Globen

The example above will match jobs that have the exact string "Globen" as the organization name. It will not match (for instance) "Globen Apeldoorn", as the full-text search would.

Snippets

When searching in the full_text field you can request snippets of the text that matched your search by using the _snippets parameter with a value of 1.

Example /search?full_text=java developer&_snippets=1

In the result the job objects will have an extra _snippets field containing an array of highlighted text snippets. For example:

"_snippets": [
    "  The Lead <em>Java<\/em> Application <em>Developer<\/em> works on the Architecture team is responsible for designing",
    " experience in at least one software specialization. The <em>Developer<\/em> acts as resource for colleagues with less",
    " experienceMinimum of 4 years <em>Java<\/em>\/ J2EE (including Servlets\/JSPs) development experienceMinimum of 4 years JDBC",
]

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 BODY
GET https://www.jobfeed.de/api/v3/aggregate?<query>
POST https://www.jobfeed.de/api/v3/aggregate <query>

Query parameters

Parameter Type Default Description
_group str None Field to aggregate on. You can specify a comma separated list to group on multiple fields (see Multi-field aggregation). It may be missing, in which case the metric will be computed on the whole result set.
_limit int 10 Limit the size of the result list. This parameter can also be used with multi-field aggregation. When grouping by date intervals there is no default value (ie: all the buckets will be returned by default), but if you do specify a _limit it will be observed.
_offset int 0 Skip a number of rows from the top of the result list.
_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.
_totals bool 0 Return total job counts from the intermediate levels of aggregation. If _metric is count_postings it returns the count of postings instead.
_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.

Grouping on ranges

When grouping by an integer field you can define buckets to group jobs into using this syntax:

fieldname__buckets_<min>_<max>_<step>
Example /aggregate?_group=salary__buckets_1000_5000_500
Description Group results by salary on buckets like 1000 → 1499, 1500 → 1999, 2000 → 2499 and so on up to 5000.

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.

Similar to multiple limits, you can specify multiple values for _offset, _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 /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.

When doing multi-field aggregations you can request the total counts from the intermediate buckets by adding the _totals=1 parameter to the request:

Example /aggregate?_labels=0&_group=profession,education_level&_totals=1
Description Group results by profession, then by education_level; also return the total count for each bucket defined by profession.

The result may look something like:

[["profession", "education_level", "count"],
 [0, 0, 18428],
 [0, 11, 8933],
 [0, 19, 8485],
 ...
 [0, 3, 592],
 [0, "_all", 49431],
 [4108, 11, 12160],
 [4108, 9, 7030],
 ...
 [4108, 7, 178],
 [4108, "_all", 37780]
 ...
]

Note the rows containing _all placeholders. They will show the total number of jobs for that profession. When using _metric=count_postings you will get the count of postings instead.

Counts

The /counts endpoint returns the count of jobs matching a set of filters, or the count of groups when grouping by a certain field.

Request

Endpoint

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

Query parameters

Parameter Type Default Description
_group str None Field to aggregate on. If missing, the number of matching jobs will be returned. If present the number of groups will be returned instead.
<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 object with a count property

Fields

The /fields endpoint provides information about all available fields: field type, English-language description, and the list of possible values (where applicable). As this request does not require a <query> only GET-requests are supported.

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.
_field str None Return information for a specific field only.
_values str None Filter possible_values object. Input is a comma separated list of keys. It should be used in combination with _field parameter, otherwise ignored.
_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