Developer Resources

Accessing the API

Our Job Postings API enables you to search for job postings by different parameters such as date, location, skills, industry, etc.

To get an API Key you need to create an account and subscribe to our Daily International Job Postings API on RapidAPI

1. Searching for Job Postings

The API returns the paginated search result with 10 full jobs for each search query. The returned JSON is described in our API docs and mainly consist of an JSON-LD payload for each Job Posting (see JobPosting Schema) that can be integrated as-is into a webpage for search engines (e.g., see Google's info on Structured Job Posting Data).

Notes

All the parameters below can be combined - but not always work together. For example, you can use a geo bounding box with a countryCode to cut out a part of a country but you can't use a geo bounding box and a geo distance search together. We advise to start with a broad search query, check the 'totalCount' in the search result, and then constrain the query until you're satisfied.

The parameters or field values do not always exists for all jobs. For example, fields like state, postCode, or department are often empty.

You will need to add authentication header parameters for access via RapidAPI etc.

1.1 Search Query Parameters (`/api/v2/jobs/search`)

General Parameters (Required)

dateCreated: The day the job postings were posted or created, using the format 'YYYY-MM-DD'. Valid values are a date in the ISO-8601 calendar system, such as 2023-11-30, 2023-12-01, 2024-01-01, etc.
page: The page of the paginated search results starting at 1. Valid values are integers up to the total count diveded by 10, such as 1, 2, 3, etc.

Location Parameters

countryCode: The country the jobs should be located in. Valid values are a 2-letter country code from ISO 3166-1 alpha-2, such as us, uk, de, es, etc.
state: The state the work place is located in. Valid are fee-text values as stated in the job posting, such as tx, england, ontario, bavaria, bayern, etc.
city: The city the work place is located in. Valid are fee-text values as stated in the job posting, such as new york, london, berlin, hong kong, bangalore, москва, etc.
postCode: The postal code the work place is located in. Valid are fee-text values as stated in the job posting, such as 1010, 00560, se1, 08160-335, b30 2qq, se26 4, etc.
timezone: The timezone the jobs are located in, such as 'CET', 'PST', or 'UTC'. Valid values are a timezone abbreviation code from IANA time zone database, such as cet, pst, utc, nzdt, etc.
timezoneOffset: The numeric offset of the timezone from UTC such as '2', '0', or '-2'. Valid offsets are integer values based on UTC+0 from -12 to 12 (not using "+")

Timezone range Parameters

timezoneMin: The minimum numeric timezone used in the search. Valid offsets are integer values based on UTC+0 from -12 to 11 (not using "+") Please note that timezoneMin must be lower than timezoneMax!
timezoneMax: The maximum numeric timezone used in the search. Valid offsets are integer values based on UTC+0 from -11 to 12 (not using "+") Please note that timezoneMin must be lower than timezoneMax!

Geographic Distance Parameters

geoPointLat: The geographic latitude (north to south coordinate) the job should be located. Valid values are a latitude based on WGS84 from -90 to +90, such as 52.25, 0.3, -77, etc.
geoPointLng: The geographic longitude (east to west coordinate) the job should be located. Valid values are a longitude based on WGS84 from -180 to +180, such as -122.449, -0.555, 123, etc.
geoDistance: The distance around the geoPoint to search for jobs. Defaults to 10km. Valid values are a decimal number of the radius in kilometer (default) or miles, such as 10km, 10mi, 50, etc.

Geographic Bounding Box Parameters

geoTopLeftLat: The geographic latitude of the top left point in a bounding box the job should be located. Valid values are a latitude based on WGS84 from -90 to +90, such as 52.25, 0.3, -77, etc.
geoTopLeftLng: The geographic longitude of the top left point in a bounding box the job should be located. Valid values are a longitude based on WGS84 from -180 to +180, such as -122.449, -0.555, 123, etc.
geoBottomRightLat: The geographic latitude of the bottom right point in a bounding box the job should be located. Valid values are a latitude based on WGS84 from -90 to +90, such as 52.25, 0.3, -77, etc.
geoBottomRightLng: The geographic longitude of the bottom right point in a bounding box the job should be located. Valid values are a longitude based on WGS84 from -180 to +180, such as -122.449, -0.555, 123, etc.

Job Details Parameters

title: Free-text search within the title of the job postings supporting Must searches (+), Must_Not searches (-) and keyword phrases (in double quotes). Normal "+" or comma "," signs will be converted into spaces. Keywords or Keyphrases without a plus or minus sign are optional but ONE of them should exist.
language: The language used in the description of the job postings. Valid values are defined by ISO 639 alpha-2, such as en, de, zh, or es.
locale: The locale used in the description of the job postings. Valid values are defined by Java's Locale class and contain the language and country codes, such as en_US, en_UK, de_DE, de_CH, zh_TW, es_US, or pt_BR.
skills: The skills, keywords, or tags identified in the job posting. Valid values are skills, technologies, or tools, such as javascript, microsoft office, azure, itil, sql, scrum, or driving licence b.
company: The company that posted the job ad. Valid values free text names of hiring or recruiting companies, such as microsoft, sap, manpower, adecco, u.s. navy, walmart, or deutsche bahn.

Job Categorization Parameters

workPlace: The place where the employee can / has to work at. Valid values are remote, hybrid, onsite, field, and offshore.
workType: The days of week or hours a day the employee can / has to work. Valid values are fulltime, parttime, flextime, shift, or fifo.
contractType: The duration or type of the employment contract. Valid values are permanent, temporary, seasonal, employeeleasing, directemployment, recruitmentreserve, contract, freelance, commission, apprenticeship, internship, or voluntary.
occupation: The normalized type of occupation identified in the job posting title. Valid are values such as programmer (synonym for software developer roles), executive (synonym for performing roles), manager (i.e., synonym for managerial roles), engineer, nurse, etc. Further specialization is possible such as java programmer, hr manager, customer success executive etc.
department: The department or 'employment unit' identified in the job posting. Valid values are sales, customer support, hr, finance, marketing, legal, it, and tax.
industry: The company's industry identified in the job posting. Valid values areadvertising, agriculture, automotive, beauty, charity, chemical, clothing, construction, consulting, education, electronic, energy, engineering, entertainment, environmental, finance, food, gastronomy, governmental, hardware, healthcare, insurance, it, legal, logistics, media, pharma, production, real estate, research, resource, security, semiconductor, services, social services, software, sport, telecom, tourism, trade, andtransport.

1.2 Search Query Usage Examples

Remote jobs in core US Timezones (UTC-8 to UTC-5):
/api/v2/jobs/search?dateCreated=2023-11-01&page=1&workPlace=remote&timezoneMin=-8&timezoneMax=-5
Jobs in southern Netherlands below latitude 52.25:
/api/v2/jobs/search?dateCreated=2023-11-01&page=1&countryCode=nl&geoTopLeftLat=52.25&geoTopLeftLng=0&geoBottomRightLat=32.25&geoBottomRightLng=10
Jobs in the Healthcare industry of the United Kingdom:
/api/v2/jobs/search?dateCreated=2023-11-01&page=1&countryCode=uk&industry=healthcare
Jobs for Java Developers in San Francisco:
/api/v2/jobs/search?dateCreated=2023-11-01&page=1&skills=Java&occupation=java,programmer&geoPointLat=37.757&geoPointLng=-122.449&geoDistance=100mi
Jobs for JavaScript Developers in New York, USA:
/api/v2/jobs/search?dateCreated=2023-11-01&page=1&skills=JavaScript&countryCode=us&city=New%20York
Jobs in English language located in Germany:
/api/v2/jobs/search?dateCreated=2023-11-01&page=1&countryCode=de&language=en

1.3 Search Query Results

The search query returns the paginated search result with 10 full jobs. The returned JSON is described below and mainly consist of an JSON-LD payload for each Job Posting (see JobPosting Schema)

2. Getting Distinct Search Query Values

In order to identify usable field values for search query fields from the last 30 days selected users can execute aggregate queries to identify all distinct values for search fields.

Notes

This endpoint is only be available for special subscription plans.

The results are capped at 500 values and are calculated from job postings within the last month (i.e., current date minus 1 month).

The parameters or field values do not always exists for all jobs. For example, fields like 'state', 'postCode', or 'department' are often empty.

2.1 Distinct Query Parameters (Required)

A Distinct Query returns a list of distinct field values for the given query parameter in the /api/v2/jobs/search endpoint.The returned JSON is described below and mainly consist of a list of keys and the count of jobs with this field value. The only valid query fields for the Distinct Query are:

field: The meaningful field used in a search query. Valid values arecity, company, contractType, countryCode,department,industry, language, locale, occupation,skills,state, timezone,workPlace, workType.

2.2 Distinct Query Usage Examples

Used workPlace values:
/api/v2/meta/jobs/distinct?field=workPlace
Used industry values:
/api/v2/meta/jobs/distinct?field=industry

2.3 Distinct Query Results

Currently, we calculate the following statistics for the field itself:

valueCount: The total number of different values.

and the following information for each distinct value of the field:

key: The name of the value used for the field.
doc_count: The number of job postings with the value used for the field.

3. Getting Statistics on values of Query fields

In order to analyze the used field values for search query fields from the last 30 days selected users can execute aggregate queries to identify statistics on the values for search fields.

Notes

This endpoint is only be available for special subscription plans.

The results are capped at 100 values and are calculated from job postings within the last month (i.e., current date minus 1 month).

3.1 Statistics Query Parameters (Required)

A Statistics Query returns a list of distinct field values (capped at 100) for the given query parameter in the /api/v2/jobs/search endpoint with added statistics.The returned JSON is described below and mainly consist of a list of keys and the statistics for the field and distinct field value. The only valid query fields for the Statistics Query are:

field: The meaningful field used in a search query. Valid values arecity, company, contractType, countryCode,department,industry, language, locale, occupation,skills,state, timezone,workPlace, workType.

3.2 Statistics Query Usage Examples

Used workPlace values:
/api/v2/meta/jobs/statistics?field=workPlace
Used industry values:
/api/v2/meta/jobs/statistics?field=industry

3.3 Statistics Query Results

Currently, we calculate the following statistics for the field itself:

totalCount: The total number of job postings within the 30 days time frame.
docsWithValue: The number of job postings with any non-empty or non-null value.
coverage: The percentage of job postings with any non-empty or non-null value.
valueCount: The total number of different values.

and the following statistics for each distinct value of the field:

doc_count: The number of job postings with that specific value.
percentage_relative: The percentage of jobs with that specific value relative to all jobs with a value (docsWithValue).
percentage_absolute: The percentage of jobs with that specific value relative to all jobs within the time frame (totalCount).

Accessing Data Files

1. Downloading files from AWS Data Exchange

1.1 Selecting Country of interest

We have listed many of our datasets on AWS Data Exchange (ADX). You can find the list of Techmap's data products here. If you are missing a country you are interested in please send an email to our Data Team.

To get a first impression and test the workflow you can access Techmap's Luxembourg dataset for free.

1.2 List all files in the AWS S3 Bucket for a country

To list the files you're subscribed to, you can use the list-objects-v2 command. The BUCKET_ALIAS can be found in the AWS Data Exchange "Entitled Data" section in the dataset section.

aws s3api list-objects-v2
  --request-payer requester
  --bucket BUCKET_ALIAS
  --prefix COUNTRY_PREFIX

1.3 Download a file from the AWS S3 Bucket for a country

To download files you're subscribed to you can use the get-object command. For example, to download the file "techmap_jobs_lu_2023-07-01.jsonl.gz" from the Luxembourg dataset you can execute:

aws s3api get-object
  --request-payer requester
  --bucket BUCKET_ALIAS
  --key lu/techmap_jobs_lu_2023-07-01.jsonl.gz
  techmap_jobs_lu_2023-07-01.jsonl.gz

2. Downloading Data from Techmap's AWS S3 Bucket

If you have a proprietary contract with us, we offer constrained access to the data files in our AWS S3 Buckets. To list and download your ordered files you can use the following commands. Please note that you only have access to the ordered time range and countries.

2.1 List all countries in our AWS S3 Bucket

aws s3 ls
  --profile YOUR_CREDENTIALS_FOR_TECHMAP
  --summarize s3://BUCKET_NAME

2.2 List all files in US directory

aws s3 ls
  --profile YOUR_CREDENTIALS_FOR_TECHMAP
  --summarize s3://BUCKET_NAME/us/

2.3 Download one file for the USA from May 4th 2023

aws s3 cp
  --profile YOUR_CREDENTIALS_FOR_TECHMAP
  s3://BUCKET_NAME/us/techmap_jobs_us_2023-05-04.jsonl.gz .

2.4 Download all files for the USA from April 2023

aws s3 sync
  --profile YOUR_CREDENTIALS_FOR_TECHMAP
  s3://BUCKET_NAME/us/ .
  --exclude "*" --include "techmap_jobs_us_2023-04-*"

Parsing Data Files

In JavaScript / TypeScript you can easily use JSON.parse() to parse all lines in the JSON files within a directory.

const fs = require('fs');
const path = require('path');
const readline = require('readline');

const directoryPath = './techmap/files/...';

fs.readdir(directoryPath, function (err, files) {
  if (err) {
    console.log('Unable to scan directory: ' + err);
    return;
  }
  // Iterate through each file in the directory
  files.forEach(function (file) {
    // Check if file is a JSON file
    if (path.extname(file) === '.json') {
      // Read the file
      const readStream = fs.createReadStream(directoryPath + file);
      const rl = readline.createInterface({
        input: readStream,
        crlfDelay: Infinity
      });
      rl.on('line', function (line) {
        try {
          // Parse the JSON data in the line
          const jsonData = JSON.parse(line);
          // TODO: do something with the JSON - e.g., store in your own DB
          console.log(jsonData);
        } catch (err) {
          console.log('Unable to parse JSON data in file ' + file + ' on line: ' + line + ': ' + err);
        }
      });
    }
  });
});

With the Java programming language you can use Java's jasonx library to parse all lines in the JSON files within a directory.

import java.io.IOException;
import java.nio.file.*;
import java.util.List;
import java.util.stream.Collectors;
import javax.json.*;

String directoryPath = "./techmap/files/...";

// Parse all JSON files in the directory
List<JsonObject> jsonObjects = Files.list(Path.of(directoryPath))
    .filter(path -> path.toString().endsWith(".json"))
    .map(path -> {
      try (JsonReader reader = Json.createReader(Files.newBufferedReader(path))) {
        return reader.readObject();
      } catch (IOException e) {
        throw new RuntimeException(e);
      }
    })
    .collect(Collectors.toList());

// Do something with the list of JSON objects
for (JsonObject jsonObject : jsonObjects) {
  // Process each JSON object
  // TODO: do something with the JSON - e.g., store in your own DB
  System.out.println(jsonString.toString());
}

For other Programming languages see the libraries section of the JSON Homepage. And remember that we have sample data you can test with.

Need Help? If you have any additional questions about working with our Job Datasets or Data Streams, please don't hesitate to contact us. We're here to help!

Developer Resources

Accessing the API

1. Searching for Job Postings

Notes

1.1 Search Query Parameters (/api/v2/jobs/search)

General Parameters (Required)

Location Parameters

Timezone range Parameters

Geographic Distance Parameters

Geographic Bounding Box Parameters

Job Details Parameters

Job Categorization Parameters

1.2 Search Query Usage Examples

1.3 Search Query Results

2. Getting Distinct Search Query Values

Notes

2.1 Distinct Query Parameters (Required)

2.2 Distinct Query Usage Examples

2.3 Distinct Query Results

3. Getting Statistics on values of Query fields

Notes

3.1 Statistics Query Parameters (Required)

3.2 Statistics Query Usage Examples

3.3 Statistics Query Results

Accessing Data Files

1. Downloading files from AWS Data Exchange

1.1 Selecting Country of interest

1.2 List all files in the AWS S3 Bucket for a country

1.3 Download a file from the AWS S3 Bucket for a country

2. Downloading Data from Techmap's AWS S3 Bucket

2.1 List all countries in our AWS S3 Bucket

2.2 List all files in US directory

2.3 Download one file for the USA from May 4th 2023

2.4 Download all files for the USA from April 2023

Parsing Data Files

1.1 Search Query Parameters (`/api/v2/jobs/search`)