# Job Regions API Endpoint Documentation A list of regions available for job search. Source: https://jobdataapi.com/c/job-regions-api-endpoint-documentation/index.md --- ## Introduction The Job Regions endpoint allows users to retrieve a list of regions available within the jobdata API database. This endpoint is particularly useful for filtering job listings by geographic regions, enabling users to focus their job search on specific areas of interest. ## Endpoint Overview **Endpoint (list):** `/api/jobregions/` **Endpoint (single element):** `/api/jobregions/{id}/` **Method:** `GET` **Authorization Required:** Yes **Description:** This endpoint provides access to a comprehensive list of regions where job postings are available. Users can use this data to narrow down job searches based on specific geographic regions. ## Request To make a request to the Job Regions endpoint, users must include an authorization header with their API key. Below are examples of how to make requests using `curl` and Python. ### Using curl ```bash curl -X GET "https://jobdataapi.com/api/jobregions/" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Using Python ```python import requests url = "https://jobdataapi.com/api/jobregions/" headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers) print(response.json()) ``` ## Parameters This endpoint does not require any query parameters. The only requirement is the inclusion of the authorization header with the API key. ## Response The response from the Job Regions endpoint is a JSON object containing an array of regions. Each region is represented by a unique identifier and a name describing the geographic area. ### Example Response ```json [ {"id":1,"name":"North America"}, {"id":2,"name":"Europe"}, {"id":3,"name":"Asia"}, {"id":4,"name":"South America"}, {"id":5,"name":"Africa"}, {"id":6,"name":"Oceania"} ] ``` ## Use Cases - **Geographic Job Search:** Job seekers can use the regions data to filter job listings by specific geographic areas, helping them find opportunities in preferred locations. - **Regional Recruitment:** Employers and recruiters can target job postings to specific regions based on their hiring needs and preferences, ensuring they attract candidates from desired locations. - **Market Analysis:** Researchers and analysts can analyze job market trends and dynamics within different regions, providing insights into regional employment patterns and opportunities. ## Notes - Replace `YOUR_API_KEY` with your actual jobdata API key in the header when making requests. This section provides comprehensive guidance on interacting with the Job Regions endpoint, facilitating effective utilization of geographic data for job searches, recruitment, and market analysis purposes. # Job Countries API Endpoint Documentation A list of countries available for job search. Source: https://jobdataapi.com/c/job-countries-api-endpoint-documentation/index.md --- ## Introduction The Job Countries endpoint provides a comprehensive list of countries where job postings are available within the jobdata API. This endpoint enables users to filter job listings based on the country of origin, facilitating targeted job searches tailored to specific geographic locations. ## Endpoint Overview **Endpoint (list):** `/api/jobcountries/` **Endpoint (single element):** `/api/jobcountries/{id}/` **Method:** `GET` **Authorization Required:** Yes **Description:** Retrieves a list of all countries with available job postings within the jobdata API database. This endpoint is essential for users who wish to filter job listings by country, either for localized job searches or for analyzing job market trends in specific regions. ## Request To make a request to the Job Countries endpoint, users must include an authorization header with their API key. Below are examples demonstrating how to make a request using `curl` and Python. ### Using curl ```bash curl -X GET "https://jobdataapi.com/api/jobcountries/" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Using Python ```python import requests url = "https://jobdataapi.com/api/jobcountries/" headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers) print(response.json()) ``` ## Parameters This endpoint does not require any query parameters. The authorization header with the API key is the only requirement to access the data. ## Response The response from the Job Countries endpoint is a JSON object containing an array of countries with available job postings. Each country object includes information such as the country code, name, and region. ### Example Response ```json [ { "id": 236, "code": "GB", "name": "United Kingdom", "region": { "id": 3, "name": "Europe" } }, { "id": 238, "code": "US", "name": "United States", "region": { "id": 5, "name": "North America" } }, // Additional country objects... ] ``` ## Use Cases - **Localized Job Searches:** Job seekers can utilize the Job Countries endpoint to filter job listings based on their desired geographic location, allowing for more targeted job searches within specific countries. - **Market Analysis:** Researchers and analysts can leverage the country data provided by this endpoint to conduct market analysis on job trends in different regions, gaining insights into employment patterns and opportunities worldwide. - **International Recruitment:** Businesses and recruiters can use this endpoint to identify countries with high job demand or talent pools in specific industries, aiding in international recruitment efforts. ## Notes - Ensure to replace `YOUR_API_KEY` with your actual jobdata API key in the authorization header. This documentation section offers a detailed overview of how to interact with the Job Countries endpoint, enabling users to effectively filter and analyze job postings based on geographic location. # Job States API Endpoint Documentation A list of states available for job search. Source: https://jobdataapi.com/c/job-states-api-endpoint-documentation/index.md --- ## Introduction The Job States endpoint provides access to a comprehensive list of states, cantons or administrative regions where job listings are available within the jobdata API database. This endpoint allows users to filter job posts based on specific states, enabling more targeted job searches tailored to individual preferences and requirements. ## Endpoint Overview **Endpoint (list):** `/api/jobstates/` **Endpoint (single element):** `/api/jobstates/{id}/` **Method:** `GET` **Authorization Required:** Yes **Description:** Retrieves a list of all states where job listings are available within the jobdata API database. This endpoint is essential for users who wish to narrow down job searches based on geographical locations at the state level. ## Query and Filter Parameters The `jobstates_list` operation supports several parameters that allow you to refine your search for states. These parameters can be used to filter the states list based on certain criteria such as the state code, country code, and name. - **code**: Filter states by their code - usually requires the country_code or country_id parameter to be set as well to avoid results with multiple states sharing the same code as it's not a unique identifier. - **country_id**: Filter states by their country ID (see [Job Countries](/c/job-countries-api-endpoint-documentation/) endpoint for more info). - **country_code**: Filter states by their ISO 3166-1 alpha-2 country code. This parameter allows you to limit the search to states within a specific country (see [Job Countries](/c/job-countries-api-endpoint-documentation/) endpoint for more info). - **asciiname**: Filter states by their ASCII name. It's useful for ignoring diacritics and for integration in systems that do not support UTF-8. - **name**: Filter states by their name. This is useful for finding states when you have a specific name in mind. - **page**: Specifies the page number of results to return. - **page_size**: Determines the number of results per page (1 - 5000, default: 200) - requires a valid API key. ## Request To make a request to the Job States endpoint, you must include an authorization header with your API key. Below are examples demonstrating how to make a request using `curl` and Python. ### Example Request (curl) ```bash curl -X GET "https://jobdataapi.com/api/jobstates/?country_code=GB" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Example Request (Python) ```python import requests url = "https://jobdataapi.com/api/jobstates/" params = { "country_code": "GB" } headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` ## Response The response from the Job States endpoint is a JSON object containing an array of states where job listings are available. Each state is represented by various attributes including the state code, name, and associated country. ### Example Response ```json { "count": 4, "next": null, "previous": null, "results": [ { "geonameid": 2634895, "code": "WLS", "asciiname": "Wales", "name": "Wales", "country": { "id": 236, "code": "GB", "name": "United Kingdom", "region": { "id": 3, "name": "Europe" } } }, { "geonameid": 2638360, "code": "SCT", "asciiname": "Scotland", "name": "Scotland", "country": { "id": 236, "code": "GB", "name": "United Kingdom", "region": { "id": 3, "name": "Europe" } } }, { "geonameid": 2641364, "code": "NIR", "asciiname": "Northern Ireland", "name": "Northern Ireland", "country": { "id": 236, "code": "GB", "name": "United Kingdom", "region": { "id": 3, "name": "Europe" } } }, { "geonameid": 6269131, "code": "ENG", "asciiname": "England", "name": "England", "country": { "id": 236, "code": "GB", "name": "United Kingdom", "region": { "id": 3, "name": "Europe" } } } ] } ``` ## Use Cases - **Geographical Filtering:** Job search platforms can integrate the Job States endpoint to allow users to filter job listings based on specific states of interest. - **Localization:** Businesses can use state-specific job data to localize their hiring efforts, targeting candidates in specific geographical regions. - **Market Analysis:** Researchers and analysts can utilize state-level job data to perform market analysis, identifying employment trends and regional job market dynamics. ## Notes - Replace `YOUR_API_KEY` with your actual jobdata API key in the authorization header. - When using filter parameters, ensure that the values provided match the expected format and type. For instance, the `country_code` should be in the ISO 3166-1 alpha-2 format. This documentation section provides comprehensive guidance on interacting with the Job States endpoint, enabling developers, businesses, and analysts to effectively utilize geographical filtering capabilities within the jobdata API. # Job Cities API Endpoint Documentation A list of cities available for job search. Source: https://jobdataapi.com/c/job-cities-api-endpoint-documentation/index.md --- ## Introduction The Job Cities endpoint facilitates access to a comprehensive list of cities where job listings are available within the jobdata API database. This endpoint empowers users to filter job posts based on specific geographical locations, enabling more targeted job searches tailored to individual preferences and requirements. ## Endpoint Overview **Endpoint (list):** `/api/jobcities/` **Endpoint (single element):** `/api/jobcities/{id}/` **Method:** `GET` **Authorization Required:** Yes **Description:** Retrieves a list of all cities where job listings are available within the jobdata API database. This endpoint is essential for users who wish to narrow down job searches based on geographical locations. ## Query and Filter Parameters The `jobcities_list` operation supports several parameters that allow you to refine your search for cities. These parameters can be used to filter the cities list based on certain criteria such as the name, country code, and pagination options. - **country_id**: Filter cities by their country ID. This allows you to limit the search to cities within a specific country (see [Job Countries](/c/job-countries-api-endpoint-documentation/) endpoint for more info). - **country_code**: Filter cities by their ISO 3166-1 alpha-2 country code. This parameter allows you to limit the search to cities within a specific country (see [Job Countries](/c/job-countries-api-endpoint-documentation/) endpoint for more info). - **state_id**: Filter cities by their state ID. This allows you to limit the search to cities within a specific state, canton or administrative region (see [Job States](/c/job-states-api-endpoint-documentation/) endpoint for more info). - **state_code**: Filter cities by their ISO 3166-1 alpha-2 country code. This parameter allows you to limit the search to cities within a specific state, canton or administrative region. It usually requires the country_code or country_id parameter to be set as well to avoid results from different states with the same code as it's not a unique identifier (see [Job States](/c/job-states-api-endpoint-documentation/) endpoint for more info). - **asciiname**: Filter cities by their ASCII name. It's useful for ignoring diacritics and for integration in systems that do not support UTF-8. - **name**: Filter cities by their name. This is useful for finding cities when you have a specific name in mind. - **min_population**: Filter cities by minimum population number. - **max_population**: Filter cities by maximum population number. - **page**: Specifies the page number of results to return. - **page_size**: Determines the number of results per page (1 - 5000, default: 200) - requires a valid API key. ## Request To make a request to the Job Cities endpoint, you must include an authorization header with your API key. Below are examples demonstrating how to make a request using `curl` and Python. ### Example Request (curl) ```bash curl -X GET "https://jobdataapi.com/api/jobcities/?country_code=US&name=New York&page=1&page_size=100" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Example Request (Python) ```python import requests url = "https://jobdataapi.com/api/jobcities/" params = { "country_code": "US", "name": "New York" } headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` ## Response The response from the Job Cities endpoint is a JSON object containing an array of cities where job listings are available. Each city is represented by various attributes including the city name, country, timezone, latitude, and longitude. ### Example Response ```json { "count": 3, "next": null, "previous": null, "results": [ { "geonameid": 5128581, "asciiname": "New York City", "name": "New York City", "country": { "id": 238, "code": "US", "name": "United States", "region": { "id": 5, "name": "North America" } }, "timezone": "America/New_York", "latitude": "40.71427", "longitude": "-74.00597", "population": 8804190 }, { "geonameid": 5115985, "asciiname": "East New York", "name": "East New York", "country": { "id": 238, "code": "US", "name": "United States", "region": { "id": 5, "name": "North America" } }, "timezone": "America/New_York", "latitude": "40.66677", "longitude": "-73.88236", "population": 173198 }, { "geonameid": 5106292, "asciiname": "West New York", "name": "West New York", "country": { "id": 238, "code": "US", "name": "United States", "region": { "id": 5, "name": "North America" } }, "timezone": "America/New_York", "latitude": "40.78788", "longitude": "-74.01431", "population": 53366 } ] } ``` ## Use Cases - **Geographical Filtering:** Job search platforms can integrate the Job Cities endpoint to allow users to filter job listings based on specific cities of interest. - **Localization:** Businesses can use city-specific job data to localize their hiring efforts, targeting candidates in specific geographical regions. - **Market Analysis:** Researchers and analysts can utilize city-level job data to perform market analysis, identifying employment trends and regional job market dynamics. ## Notes - Replace `YOUR_API_KEY` with your actual jobdata API key in the authorization header. - When using filter parameters, it's important to ensure that the values provided match the expected format and type. For instance, the `country_code` should be in the ISO 3166-1 alpha-2 format, and pagination parameters like `page` and `page_size` should be integers. This documentation section provides comprehensive guidance on interacting with the Job Cities endpoint, enabling developers, businesses, and analysts to effectively utilize geographical filtering capabilities within the jobdata API. # Job Types API Endpoint Documentation A list of job types available for job search. Source: https://jobdataapi.com/c/job-types-api-endpoint-documentation/index.md --- ## Introduction The Job Types endpoint provides a comprehensive list of job types available in the jobdata API, enabling users to filter job posts based on the type of employment they offer, such as full-time, part-time, contract, temporary, etc. This capability allows for more targeted job searches, catering to the specific needs and preferences of job seekers and businesses looking for particular types of hires. ## Endpoint Overview **Endpoint (list):** `/api/jobtypes/` **Endpoint (single element):** `/api/jobtypes/{id}/` **Method:** `GET` **Authorization Required:** Yes **Description:** Retrieves a list of all job types available within the jobdata API database. This endpoint is instrumental for users who wish to categorize or filter job listings by the nature of the employment contract offered by the hiring companies. ## Request To make a request to the Job Types endpoint, you must include an authorization header with your API key. Here is how you can make a request using `curl` and Python. ### Using curl ```bash curl -X GET "https://jobdataapi.com/api/jobtypes/" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Using Python ```python import requests url = "https://jobdataapi.com/api/jobtypes/" headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers) print(response.json()) ``` ## Parameters This endpoint does not require any query parameters. The authorization header is the only requirement to access the data. ## Response The response from the Job Types endpoint is a JSON object containing an array of job types. Each job type is represented by a unique identifier and a name describing the type of employment. ### Example Response ```json [ {"id":1, "name":"Full Time"}, {"id":2, "name":"Part Time"}, {"id":3, "name":"Temporary"}, {"id":4, "name":"Internship"}, {"id":5, "name":"Freelance"}, {"id":6, "name":"Contract"}, {"id":7, "name":"Apprenticeship"} ] ``` ## Use Cases - **Job Search Platforms:** Integrators can use the Job Types endpoint to build filters in their job search platforms, allowing users to narrow down their job search based on the type of employment they are interested in. - **HR Software:** HR software solutions can integrate this endpoint to help businesses post jobs with specific employment types, ensuring they attract the right candidates. - **Data Analysis:** Researchers and analysts can use the job types data to conduct market analysis on employment trends, offering insights into the most popular job types and emerging employment patterns. ## Notes - Remember to replace `YOUR_API_KEY` with your actual jobdata API key in the header. This section of the documentation provides a detailed overview of how to interact with the Job Types endpoint, ensuring that developers, businesses, and job search platforms can effectively utilize this information to enhance their applications and services. # Jobs API Endpoint Documentation Fetching job listings with advanced filters. Source: https://jobdataapi.com/c/jobs-api-endpoint-documentation/index.md --- ## Introduction The Jobs endpoint is a powerful feature of the jobdata API, designed to offer comprehensive access to job postings from thousands of companies across various industries. This endpoint facilitates the retrieval of job listings with detailed information, including job title, location, company details, job type, and more. It caters to a wide range of users, from job search platforms to HR software, enabling them to access up-to-date job data directly from companies' ATS (Applicant Tracking System) and career platforms. ## Endpoint Overview **Endpoint (list):** `/api/jobs/` **Endpoint (single element):** `/api/jobs/{id}/` **Method:** `GET` **Authorization Required:** Yes **Description:** This endpoint allows users to fetch job listings based on various filters such as company name, job title, location, and more. Each job listing includes comprehensive details about the job, such as the company information, job type, application link, and description. It's designed to provide quality job data for various applications, including job search engines, market analysis, and HR solutions. ## Request To access the Jobs endpoint, include an authorization header with your API key. Here's how to make a request using both `curl` and Python. ### Using curl ```bash curl -X GET "https://jobdataapi.com/api/jobs/?title=Software%20Engineer&location=New%20York" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Using Python ```python import requests url = "https://jobdataapi.com/api/jobs/" params = {"title": "Software Engineer", "location": "New York"} headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers, params=params) print(response.json()) ``` ## Parameters The Jobs endpoint supports several parameters for filtering job listings or adding additional fields, enhancing the flexibility and precision of job searches. Some parameters allow for multiple values be set to get even more precise with narrowing down a query. These are indicated by an **[[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]** *=multi-ID*, **[[mc](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]** *=multi-code*, and **[[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]** *=multi-keyword* right behind their parameter name. - **include_agencies**: Includes jobs from recruiting/staffing agencies in the results. Can be `true` or `false` - the default is `false` internally. So when no `include_agencies=true` is added as a query parameter, job listings from agencies are excluded from all results. - **company_is_agency**: Show listings from either recruiting/staffing agencies (with `company_is_agency=true`) or only from companies hiring directly with `company_is_agency=false` (the default is `false` internally). - **company_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the ID of the company offering the job - requires a [valid API key](/accounts/pricing/). - **company_source_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by their companies' source/ATS ID - requires **access pro** subscription. - **company_name** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filters jobs by the name of the company offering the job(s). - **company_website** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filters jobs by a company domain name or its website URL. - **region_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the region ID where the job is located (see [Job Regions endpoint](/c/job-regions-api-endpoint-documentation/) for more info). - **country_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the country ID of the job location (see [Job Countries](/c/job-countries-api-endpoint-documentation/) endpoint for more info). - **country_code** [[mc](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the country code of the job location (ISO 3166-1 alpha-2 code, see [Job Countries](/c/job-countries-api-endpoint-documentation/) endpoint for more info). - **state_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the state ID of the job location (see [Job States](/c/job-states-api-endpoint-documentation/) endpoint for more info). - **state_code** [[mc](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the state code of the job location. This usually requires the country_code or country_id parameter to be set as well to avoid results from different states with the same code as it's not a unique identifier (see [Job States](/c/job-states-api-endpoint-documentation/) endpoint for more info). - **city_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the city ID of the job location (see [Job Cities](/c/job-cities-api-endpoint-documentation/) endpoint for more info). - **city_name** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filters jobs by the name (or substring) of the city where the job is located. - **description**: Filters jobs by keywords or phrases in the job description, see the [full-text search documentation](/c/full-text-search-on-job-descriptions/) page for more details - requires **access pro** subscription. - **description_md**: When used with value `true` this adds an additional field `description_md` to every result set object containing a Markdown version of the description string. Note: it is recommended to add the `description_off=true` parameter to remove the HTML description variant - if not needed - from the result to speed up response times and save on bandwidth. - **description_str**: When used with value `true` this adds an additional field `description_string` to every result set object containing a stripped version of the description string without any html tags and other non-text/informational data. - **description_off**: When used with value `true` this parameter hides the original HTML description from the results. - **vec_text**: Accepts a string (up to 1000 characters) for vector search. The API converts this string into embeddings in real-time and returns job postings based on their cosine similarity to the generated embeddings, see the [vector embeddings and search documentation](/c/vector-embeddings-and-search-api-documentation/)) page for more details - requires **access pro+** subscription. - **vec_embedding** (POST only): Matches jobs against a given array of 768 floats representing a 768-dimensional embedding in half-precision, see the [vector embeddings and search documentation](/c/vector-embeddings-and-search-api-documentation/)) page for more details - requires **access pro+** subscription. - **max_dist**: Definies the maximum value for the cosine distance to be applied during vector similarity search. Must be a value between `0.1 - 0.9`, see the [vector embeddings and search documentation](/c/vector-embeddings-and-search-api-documentation/)) page for more details - requires **access pro+** subscription. - **embed_3sh**: When set to `true`, this parameter activates the `embedding_3sh` field in the job listings, providing pre-generated embeddings with 768 dimensions at half-precision, see the [vector embeddings and search documentation](/c/vector-embeddings-and-search-api-documentation/)) page for more details - requires **access pro+** subscription. - **exclude_expired**: Excludes expired job listings from the results when set to `true` - requires **access pro** subscription. - **type_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the job type ID (see [Job Types endpoint](/c/job-types-api-endpoint-documentation/) for more info). - **experience_level**: Filters jobs by the required experience level (`EN` for Entry Level, `MI` for Mid Level, `SE` for Senior Level and `EX` for Executive level). - **has_remote**: Filters jobs based on whether they offer remote work options (value can be `true` or `false` for filtering either all non-remote or remote/wfh/hybrid listings). - **language** [[mc](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the language in which the job post is written (ISO 639 language code, e.g. `en`, `fr`, `de`, etc. - see all available codes on the [language stats](/language-stats/) page). - **title** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filters jobs by a substring contained within their title. - **location** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filters jobs by a string within the general location description that comes with a job post, also allows for an `|OR|` operater (see [details below](/c/jobs-api-endpoint-documentation/#using-the-or-operator-in-location-and-title-queries)). - **location_str**: When used with value `true` this adds an additional field `location_string` to every result set object containing a GeoNames-optimized location string ([Changelog v4.3](/c/new-location-id-fields-and-filters/)). - **max_age**: Filters jobs by the maximum age (in days, 1 - 999) since they were published. - **published_since**: Filters jobs published since a specific date (`YYYY-MM-DD`). - **published_until**: Filters jobs published until a specific date (`YYYY-MM-DD`). - **min_salary**: Filters jobs by the minimum [yearly salary (FTE)](/c/converting-annual-fte-salary-to-monthly-weekly-daily-and-hourly-rates/) offered. - **max_salary**: Filters jobs by the maximum [yearly salary (FTE)](/c/converting-annual-fte-salary-to-monthly-weekly-daily-and-hourly-rates/) offered. - **salary_currency**: Filters jobs by the currency of the salary offered (see [available currency values below](/c/jobs-api-endpoint-documentation/#salary-currency-parameter-values)). - **min_salary_usd**: Filters jobs by the minimum [yearly salary (FTE)](/c/converting-annual-fte-salary-to-monthly-weekly-daily-and-hourly-rates/) offered, indexed to its [FX rate in USD](/c/currency-rates-api-endpoint-documentation/) - requires **access pro+** subscription. - **max_salary_usd**: Filters jobs by the maximum [yearly salary (FTE)](/c/converting-annual-fte-salary-to-monthly-weekly-daily-and-hourly-rates/) offered, indexed to its [FX rate in USD](/c/currency-rates-api-endpoint-documentation/) - requires **access pro+** subscription. - **min_salary_eur**: Filters jobs by the minimum [yearly salary (FTE)](/c/converting-annual-fte-salary-to-monthly-weekly-daily-and-hourly-rates/) offered, indexed to its [FX rate in EUR](/c/currency-rates-api-endpoint-documentation/) - requires **access pro+** subscription. - **max_salary_eur**: Filters jobs by the maximum [yearly salary (FTE)](/c/converting-annual-fte-salary-to-monthly-weekly-daily-and-hourly-rates/) offered, indexed to its [FX rate in EUR](/c/currency-rates-api-endpoint-documentation/) - requires **access pro+** subscription. - **salary_extras**: When set to `true`, this parameter activates the `salary_min_est`, `salary_max_est`, `salary_min_usd`, `salary_max_usd`, `salary_min_eur` and `salary_max_eur` fields in each job listing, providing pre-computed estimate salary values and base-currency indexing in USD and EUR (where available) - requires **access pro+** subscription. - **application_url** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filters jobs based on text within the application_url field value. It provides a LIKE search to find jobs associated with specific domains or parts of a URL - requires **access pro** subscription. - **min_id**: Filters for all jobs that have a job ID equal or larger - requires a [valid API key](/accounts/pricing/). - **max_id**: Filters for all jobs that have a job ID equal or smaller - requires a [valid API key](/accounts/pricing/). - **page**: Specifies the page number in the paginated result set - requires a [valid API key](/accounts/pricing/). - **page_size**: Determines the number of results per page (1 - 5000, default: 200) - requires a [valid API key](/accounts/pricing/). ### Advanced Company Info Parameters The following company-related query parameters require an **access pro** subscription: - **company_founded_after**: Filters companies by their founding year, selecting those founded after the specified year. - **company_founded_before**: Filters companies by their founding year, selecting those founded before the specified year. - **company_founded_in**: Filters companies by their exact founding year. - **company_description** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filters jobs by a search term in the company description. - **company_hq** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filters jobs by the headquarters location of the company offering the job. - **company_hq_region_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters companies by the region ID their headquarters are located in (see [Job Regions endpoint](/c/job-regions-api-endpoint-documentation/) for more info). - **company_hq_country_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters companies by the country ID their headquarters are located in (see [Job Countries](/c/job-countries-api-endpoint-documentation/) endpoint for more info). - **company_hq_state_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters companies by the state ID their headquarters are located in (see [Job States](/c/job-states-api-endpoint-documentation/) endpoint for more info). - **company_hq_city_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters companies by the city ID their headquarters are located in (see [Job Cities](/c/job-cities-api-endpoint-documentation/) endpoint for more info). - **company_industry_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the industry ID of the company offering the job (see [Industries endpoint](/c/industries-api-endpoint-documentation/) for more info). - **company_max_size**: Filters jobs by companies and their maximum size (number of employees). - **company_min_size**: Filters jobs by companies and their minimum size (number of employees). - **company_specialty** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filters jobs by the specialty or focus area of the hiring company. - **company_type_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the type ID of the company offering the job (see [Company Types endpoint](/c/company-types-api-endpoint-documentation/) for more info). Also see the [Companies API Endpoint Documentation](/c/companies-api-endpoint-documentation/) for more info on company attributes. ### Salary Currency Parameter Values The list of currently available salary currencies for the `/api/jobs/` endpoint in the jobdata API is as follows: - AUD (Australian Dollar) - THB (Baht) - BRL (Brazilian Real) - BGN (Bulgarian Lev) - CAD (Canadian Dollar) - CLP (Chilean peso) - CNY (Chinese yuan) - COP (Colombian Peso) - CZK (Czech Koruna) - DKK (Danish Krone) - EUR (Euro) - HUF (Forint) - HKD (Hong Kong Dollar) - INR (Indian Rupee) - MYR (Malaysian ringgit) - MXN (Mexican peso) - ILS (New Israeli Sheqel) - TWD (New Taiwan Dollar) - NZD (New Zealand Dollar) - NGN (Nigerian naira) - NOK (Norwegian Krone) - PHP (Philippine Peso) - GBP (Pound Sterling) - ZAR (Rand) - RON (Romanian Leu) - IDR (Rupiah) - SGD (Singapore Dollar) - KRW (South Korean Won) - LKR (Sri Lankan Rupee) - SEK (Swedish Krona) - CHF (Swiss Franc) - TRY (Turkish Lira) - UAH (Ukrainian hryvnia) - AED (United Arab Emirates Dirham) - USD (US Dollar) - JPY (Yen) - PLN (Zloty) These currencies provide a broad spectrum for specifying salary ranges in job postings, accommodating the global reach of job listings available through the jobdata API. You can specify the `salary_currency` query parameter to filter job listings based on their actual currency for salary information. ## Response The response from the Jobs endpoint is a JSON object that includes a count of total job listings matching the query and an array of job details, basic company info for each job and related geolocation information. ### Top-Level Response Structure - **count**: An integer indicating the total number of job listings available that match the query. - **next**: A URI to the next page of results, if available; otherwise, null. This helps in navigating through paginated data. - **previous**: A URI to the previous page of results, if available; otherwise, null. It allows users to navigate back to the previous set of results. - **results**: An array of job listings, where each job listing is a detailed object with various attributes. ### Job Listing Structure (`results` array items) Each item in the `results` array represents a job listing with the following properties: - **id**: The unique identifier for the job listing (read-only). - **ext_id**: An optional external identifier for the job listing. - **company**: An object containing detailed information about the company posting the job. This includes the company's name, logo, website URL, and social media links, providing a comprehensive view of the employer. - **title**: The title of the job listing. - **location**: The location where the job is based. - **types**: An array of job types (e.g., full-time, part-time) associated with the job listing. - **regions**: An array of global regions associated with the job location. - **countries**: An array of countries associated with the job location, offering a broader geographical scope. - **states**: An array of states related to the job location, providing a detailed geographical context. - **cities**: An array of cities related to the job location, providing an even more detailed geographical context. - **has_remote**: A boolean indicating whether the job offers a remote working option, which is crucial for applicants looking for flexible working conditions. - **published**: The publication date and time of the job listing. - **expired**: The expired date and time of the job listing or null - requires **access pro** subscription to be shown in results. - **description**: A detailed description of the job, including responsibilities, qualifications, and other important details. - **description_md**: A Markdown version of the full job description (only shown when parameter `description_md=true` is added to a query). - **description_string**: A cleaned up and stripped version of the job description (only shown when parameter `description_str=true` is added to a query). - **experience_level**: Indicates the required experience level for applicants (e.g., entry-level, senior). - **application_url**: A URL where applicants can apply for the job directly, ensuring a seamless application process. - **language**: The language code for the job listing, indicating the required language proficiency. - **salary_min** and **salary_max**: Optional fields indicating the [minimum and maximum yearly salary (FTE)](/c/converting-annual-fte-salary-to-monthly-weekly-daily-and-hourly-rates/) for the job, providing transparency about compensation. - **salary_min_est** and **salary_max_est**: Optional fields (included when parameter `salary_extras=true` is added to a query) indicating the estimated minimum and maximum yearly salary (FTE) based on internal vector search matches with similar jobs - requires **access pro+** subscription to be shown in results. - **salary_min_usd**, **salary_max_usd**, **salary_min_eur** and **salary_max_eur**: Optional fields (included when parameter `salary_extras=true` is added to a query) indicating the given salary, or the estimate when no salary info came with the job listing, [converted to USD and EUR as base currencies](/c/currency-rates-api-endpoint-documentation/), making it easier to compare salaries across different currencies - requires **access pro+** subscription to be shown in results. - **salary_currency**: The currency of the salary, which helps applicants understand the value of the compensation in their local context (see [currency values](#salary-currency-parameter-values)). ### Example Response ```json { "count": 2, "next": "https://jobdataapi.com/api/jobs/?page=2", "previous": null, "results": [ { "id": 12345, "company": { "name": "Tech Innovations Inc.", "logo": "https://example.com/logo.png", "website_url": "https://techinnovations.com", "linkedin_url": "https://linkedin.com/company/tech-innovations-inc", ... }, "title": "Senior Software Engineer", "location": "Remote", "has_remote": true, "published": "2024-02-01", "description": "We are looking for a Senior Software Engineer...", "experience_level": "SE", "application_url": "https://techinnovations.com/careers/12345", "salary_min": "100000", "salary_max": "150000", "salary_currency": "USD", ... }, // Additional job listings... ] } ``` Here is the same response when using `salary_extras=true` as an additional query parameter: ```json { "count": 2, "next": "https://jobdataapi.com/api/jobs/?page=2", "previous": null, "results": [ { "id": 12345, "company": { "name": "Tech Innovations Inc.", "logo": "https://example.com/logo.png", "website_url": "https://techinnovations.com", "linkedin_url": "https://linkedin.com/company/tech-innovations-inc", ... }, "title": "Senior Software Engineer", "location": "Remote", "has_remote": true, "published": "2024-02-01", "description": "We are looking for a Senior Software Engineer...", "experience_level": "SE", "application_url": "https://techinnovations.com/careers/12345", "salary_min": "100000", "salary_max": "150000", "salary_currency": "USD", "salary_min_est": 92600, "salary_max_est": 187200, "salary_min_usd": 100000, "salary_max_usd": 150000, "salary_min_eur": 86153, "salary_max_eur": 129229, ... }, // Additional job listings... ] } ``` ## Use Cases - **Job Search Platforms:** Easily integrate the latest job listings into job search platforms, providing users with up-to-date information. - **HR Software:** Use the API to assist businesses in broadcasting their job openings and managing applications. - **Market Analysis:** Analysts can leverage the job data for insights into hiring trends, popular job locations, and salary benchmarks. - **Personalized Job Alerts:** Develop applications that send personalized job alerts to users based on their preferences and qualifications. ## Notes - The `has_remote` parameter is useful for platforms focusing on remote work opportunities. - The `description_str` parameter is particularly useful for saving cleaning steps in your data pipeline for further processing of job descriptions (e.g. text analysis, NLP, model training, etc.). - Use the pagination parameters (`page` and `page_size`) to manage the volume of data and navigate through large sets of job listings efficiently. - The `Authorization` header should be included in every request to authenticate your access. - The `min_id` and `max_id` parameters allow for fetching all jobs from a certain ID range/offset. This can be used to retrieve job posts in the sequence they where added in the database and not by date published for example. By leveraging the Jobs endpoint, users can tap into a vast database of job listings, enabling a wide range of applications from job discovery to market research, all backed by accurate and timely data directly from employers. # Jobs Expired API Endpoint Documentation Tracking the lifecycle of job postings. Source: https://jobdataapi.com/c/jobs-expired-api-endpoint-documentation/index.md --- ## Introduction The Expired Jobs endpoint is a powerful feature available for **access pro** subscribers of the jobdata API. It offers access to job listings that have expired, allowing users to track the lifecycle of job postings, understand hiring trends over time, and ensure that their platforms or databases maintain current and relevant job information. This capability is particularly useful for job search platforms, HR software solutions, and market research analysts looking to analyze job market dynamics and the longevity of job postings. ## Limitations Keeping up with the lifespan of millions of jobs at all times is quite resource intense and subject to some inherent limitations given by how many ATS (applicant tracking systems) work. We do our best to provide the most accurate data in time but we cannot guarantee full coverage and accuracy. At the moment about **80~90% of all jobs expired data** is on time and accurate. This also means that at any given moment up to 2 in 10 jobs might not be tracked in a timely fashion (usually with a delay of a few days though). Additionally we have an internal **180 days rule** after which jobs expire automatically in our database. This is also to distinguish real vacancies from those that companies occasionally like to keep published for years or have simply forgotten about. ## Endpoint Overview **Endpoint (list):** `/api/jobsexpired/` **Endpoint (single element, via Job ID):** `/api/jobsexpired/{id}/` **Method:** `GET` **Authorization Required:** Yes (**access pro** subscription) **Description:** Retrieves a list of job postings that have expired within a specified date range. This endpoint helps in cleaning up outdated job listings from user-facing platforms and provides valuable data for analyzing job market trends. ## Request Making a request to the Expired Jobs endpoint requires an authorization header with a pro access API key. Below are examples of how to make a request using `curl` and Python. ### Using curl ```bash curl -X GET "https://jobdataapi.com/api/jobsexpired/?country_code=US&expired_since=2023-01-01&expired_until=2023-01-31&page_size=2500" -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Using Python ```python import requests url = "https://jobdataapi.com/api/jobsexpired/" params = { "country_code": "US", "expired_since": "2024-01-01", "expired_until": "2024-01-31", "page_size": 2500 } headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, params=params, headers=headers) data = response.json() print(data) ``` Replace `YOUR_API_KEY` with your actual pro access API key. ## Parameters The Expired Jobs endpoint supports several query parameters to filter the results according to your needs. Some parameters allow for multiple values be set to get even more precise with narrowing down a query. These are indicated by an **[[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]** *=multi-ID*, **[[mc](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]** *=multi-code*, and **[[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]** *=multi-keyword* right behind their parameter name. - **expired_since**: Limits the search to jobs expired on or after this date. Format: `YYYY-MM-DD`. - **expired_until**: Limits the search to jobs expired on or before this date. Format: `YYYY-MM-DD`. - **has_remote**: Boolean flag to include jobs that offer remote work options. - **company_source_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by their companies' source/ATS ID. - **region_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the region ID where the job is located (see [Job Regions endpoint](/c/job-regions-api-endpoint-documentation/) for more info). - **country_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the country ID of the job location (see [Job Countries](/c/job-countries-api-endpoint-documentation/) endpoint for more info). - **country_code** [[mc](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the country code of the job location (ISO 3166-1 alpha-2 code, see [Job Countries](/c/job-countries-api-endpoint-documentation/) endpoint for more info). - **state_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the state ID of the job location (see [Job States](/c/job-states-api-endpoint-documentation/) endpoint for more info). - **state_code** [[mc](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the state code of the job location. This usually requires the country_code or country_id parameter to be set as well to avoid results from different states with the same code as it's not a unique identifier (see [Job States](/c/job-states-api-endpoint-documentation/) endpoint for more info). - **city_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters jobs by the city ID of the job location (see [Job Cities](/c/job-cities-api-endpoint-documentation/) endpoint for more info). - **language** [[mc](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filters results based on the job listing's language (ISO 639 language code, e.g. `en`, `fr`, `de`, etc. - see all available codes on the [langauge stats](/language-stats/) page). - **application_url** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filters jobs based on text within the application_url field value. It provides a LIKE search to find jobs associated with specific domains or parts of a URL. - **max_age**: Specifies the maximum age of the job listing before it expired, in days. - **published_since**: Filters jobs that were published on or after this date. Format: `YYYY-MM-DD`. - **published_until**: Filters jobs that were published on or before this date. Format: `YYYY-MM-DD`. - **min_id**: Filters for all jobs that have a job ID equal or larger - requires a valid API key. - **max_id**: Filters for all jobs that have a job ID equal or smaller - requires a valid API key. - **page**: Specifies the page number of results to return - requires a valid [access pro](/accounts/pricing/) API key, otherwise using this parameter will return an empty result. - **page_size**: Determines the number of results per page (1 - 5000, default: 200) - requires a valid [access pro](/accounts/pricing/) API key, otherwise using this parameter will return an empty result. ## Response The response from the Expired Jobs endpoint is a JSON object containing a list of expired job postings. Each entry includes details such as the job ID, external ID, the date it expired, the date it was published, the job title, and the application URL. When querying a single job via its ID (through `/api/jobsexpired/{id}/`) a full JSON response will be returned in case the job has expired. If not, a **404 response** (not found) will be returned, which means there's no expired info available for that given job and the listing is still live (or doesn't exist at all in our database). ### Response Structure The API employs pagination to manage large sets of results efficiently, making the data easier to handle by breaking it into smaller, manageable pages. The paginated response includes: - **count**: An integer representing the total number of expired job postings that match the query criteria. This helps in understanding the scope of the data and planning navigation through paginated results. - **next**: A URL string pointing to the next page of results. This is particularly useful for iterative fetching in applications that process or display large datasets. It will be `null` if there is no next page. - **previous**: A URL string pointing to the previous page of results. Similar to `next`, it assists in navigating through pages but in the reverse direction. It will be `null` on the first page. - **results**: An array of objects, each representing an expired job posting. This array holds the actual data you're interested in and may contain multiple job postings, depending on the `page_size` specified in the request. #### Job Postings (`results` Array) Each object in the `results` array provides detailed information about a specific expired job posting: - **id**: A unique integer identifier for the job posting within the jobdata API system. This ID can be used for referencing or querying specific job postings in other API operations. - **ext_id**: A string representing an external identifier for the job posting, if available. This could be useful for correlating job postings with external systems or databases. - **expired**: A string in ISO 8601 date format (`YYYY-MM-DDTHH:MM:SSZ`), indicating when the job posting expired. This timestamp is crucial for understanding the timing of job postings and their relevance. - **published**: A string in ISO 8601 date format (`YYYY-MM-DDTHH:MM:SSZ`), showing when the job posting was initially published. Analyzing the duration between `published` and `expired` can provide insights into how long job opportunities typically remain open. - **title**: A string containing the title of the job posting. This gives a quick overview of the job's nature or position. - **application_url**: A URL string where candidates could have applied for the job or obtained more information. While the job is expired, this link may still offer insights into the employer's hiring process or lead to similar, active opportunities. ### Example Response ```json { "count": 2, "next": null, "previous": null, "results": [ { "id": 12345, "ext_id": "XYZ987", "expired": "2024-02-08T03:55:02.619747Z", "published": "2024-01-12T20:49:08Z", "title": "Software Engineer", "application_url": "https://example.com/job/12345/apply" }, { "id": 67890, "ext_id": "ABC123", "expired": "2024-02-08T03:55:02.619747Z", "published": "2023-12-17T20:50:19Z", "title": "Product Manager", "application_url": "https://example.com/job/67890/apply" } ] } ``` ## Use Cases - **Job Search Platforms:** Automatically remove or archive listings that have expired, maintaining a current and relevant job board for users. - **HR Software:** Monitor the lifecycle of job postings to optimize posting strategies and improve candidate attraction. - **Market Research:** Analyze job expiration data to identify hiring trends, peak hiring seasons, and the average duration jobs stay posted. ## Notes - The `expired_since` and `expired_until` parameters can be used together to define a specific date range for the expired job posts you're interested in. - To filter by a sequence of job IDs the `min_id` and `max_id` parameters can be used to define a range, offset or limit here instead of - or combined with - date filter query parameters. - The `has_remote` parameter is particularly useful for platforms focusing on remote work opportunities. - Pagination parameters (`page` and `page_size`) are essential for handling large datasets and improving the manageability of the API response. - This endpoint is only accessible to users with an **access pro** subscription to the jobdata API. - It is crucial to replace `YOUR_API_KEY` with your actual jobdata API key in the authorization header to successfully make requests. This documentation section provides a comprehensive overview of the Expired Jobs endpoint, ensuring that developers and businesses can effectively utilize this feature to enhance their services or gain insights into job market trends. # Full-Text Search on Job Descriptions Leverage precise text queries to navigate millions of job descriptions. Source: https://jobdataapi.com/c/full-text-search-on-job-descriptions/index.md --- ## Introduction The jobdata API's `/api/jobs/` endpoint features a full-text search capability available for **access pro** subscribers. This functionality enables users to perform detailed and nuanced searches within job descriptions. This section provides comprehensive guidance on using the `description` query parameter to refine your job search with precision. ## Search Index The search index is built from two key job data fields: the **description_string**, which is a cleaned version of the job description stripped of any HTML tags and non-text elements, ensuring that the search focuses solely on the relevant textual content, and the **title**, which is also included in the search index to enhance the relevance of search results. By leveraging both the cleaned job description and the job title, the full-text search capability allows users to perform nuanced queries that effectively match job listings based on specific skills, phrases, or keywords. ## Endpoint Overview **URL:** `/api/jobs/` **Method:** `GET` **Authorization Required:** Yes (**access pro** subscription) **Description:** This endpoint is essential to find jobs that match specific criteria, such as required skills, job titles, or phrases mentioned within job descriptions. ## Query Parameter - **description** (string, optional): Executes full-text search queries against job descriptions. ## How Full-Text Search Operates The `description` parameter leverages full-text search capabilities, translating user queries into powerful search operations that understand logical operators and phrase matching. The parameter supports: - **Unquoted text:** Terms not enclosed in quotes are treated as separate search terms (will be converted to terms separated by & operators internally). - **"Quoted text":** Text within quotes is treated as a single search phrase. - **OR:** The word "or" between terms allows for searches that match any of the specified terms. - **- (Dash):** A dash before a term translates to the `!` operator, excluding terms from search results. ## Example Usage ### Simple Keyword Search #### Using curl ```sh curl -X GET "https://jobdataapi.com/api/jobs/?description=python+django" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` #### Using Python ```python import requests url = "https://jobdataapi.com/api/jobs/" params = { "description": "python django" } headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` This query searches for job descriptions containing both "python" and "django". ### Phrase Search #### Using curl ```sh curl -X GET "https://jobdataapi.com/api/jobs/?description=%22senior+developer%22" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` #### Using Python ```python import requests url = "https://jobdataapi.com/api/jobs/" params = { "description": '"senior developer"' } headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` Searches for jobs where "senior" and "developer" appear as a consecutive phrase. ### Combining Keywords and Phrases #### Using curl ```sh curl -X GET "https://jobdataapi.com/api/jobs/?description=python+%22software+engineer%22" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` #### Using Python ```python import requests url = "https://jobdataapi.com/api/jobs/" params = { "description": 'python "software engineer"' } headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` Finds jobs mentioning "python" and the exact phrase "software engineer". ### Including and Excluding Terms #### Using curl ```sh curl -X GET "https://jobdataapi.com/api/jobs/?description=python+-java+OR+ruby+-java" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` #### Using Python ```python import requests url = "https://jobdataapi.com/api/jobs/" params = { "description": 'python -java OR ruby -java' } headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, params=params, headers=headers) print(response.json()) ``` Looks for jobs mentioning either "python" or "ruby" but excludes any jobs mentioning "java". ## Response Upon successfully executing a search query against the `/api/jobs/` endpoint, the API returns a structured JSON response containing a paginated list of job listings that match the provided search criteria. Each job listing within the response is comprehensive, offering detailed information about the position, including the full job description. ```json { "count": 123, "next": "https://jobdataapi.com/api/jobs/?page=2", "previous": null, "results": [ { "id": 1, "company": { "name": "Company A", "logo": "URL_to_logo", "website_url": "URL_to_company_website", ... }, "title": "Job Title", "location": "Job Location", "description": "Full job description text here, detailing responsibilities, qualifications, and other important information..." ... }, ... ] } ``` ## Tips for Crafting Effective Queries - **Unquoted vs. Quoted:** Use unquoted text for broad searches across multiple terms and quoted text for precise phrase matches. - **Logical Operators:** Utilize "OR" and "-" to expand or narrow your search scope as needed. - **Experimentation:** Different combinations of keywords, phrases, and operators can yield varied and sometimes more relevant results. ## Notes - Access to this search requires authentication via the `Authorization` header, including a valid API key. Replace `YOUR_API_KEY` with your actual API key in the sample requests. - A full-text search query can be combined with any of the other query parameters available on the `/api/jobs/` endpoint. - This feature is available to **access pro** subscribers only (without it, using the description parameter returns an empty result). Leveraging the full-text search feature enhances job discovery by enabling detailed queries across the extensive database of job descriptions. This allows users to pinpoint jobs that align closely with their skills, experiences, and career aspirations. # Multi-value Parameters Documentation Narrow down your job and company data queries or get even more flexible with our multi-value parameters. Source: https://jobdataapi.com/c/multi-value-parameters-documentation/index.md --- ## Overview Some parameters in the Jobs, Jobs expired and Company API endpoints support multiple values, indicated by the following suffixes: - **[mi]**: Multi-ID (e.g., `type_id`, `company_id`, etc.) - **[mc]**: Multi-code (e.g., `country_code`, `state_code`, etc.) - **[mk]**: Multi-keyword (e.g., `company_name`, `company_specialty`, etc.) These multi-value parameters allow you to combine or exclude multiple values in a single query, making your searches more efficient and flexible. ## How It Works ### Multi-ID and Multi-Code Parameters For parameters that accept multiple IDs or codes, you can separate values using the pipe (`|`) character. You can also exclude specific values by prefixing them with a minus sign (`-`). You can combine up to 50 IDs or codes at maximum. **Examples**: - **Include multiple values**: `https://jobdataapi.com/api/jobs/?type_id=1|4` This query retrieves jobs with `type_id` equal to 1 **OR** 4. - **Exclude specific values**: `https://jobdataapi.com/api/jobs/?country_code=-CA|-US` This query excludes jobs from Canada (`CA`) and the United States (`US`). - **Combine inclusion and exclusion**: `https://jobdataapi.com/api/jobs/?type_id=1|4|-5|-6` This query retrieves all jobs with `type_id` equal to 1 **OR** 4 but excludes those that contain either 5 **OR** 6. Combining includes and excludes makes sense where a listing can have multiple values, as with job types here (e.g. all jobs with Full-time or Internship but not Freelance or Contract for any of those). ### Multi-Keyword Parameters For parameters that accept multiple keywords (or substrings, as in a `LIKE` SQL matching operation), you can use the `|OR|` operator ("pipe" "*uppercase* OR" "pipe") to combine keywords. This allows you to search for jobs or companies that match **any** of the specified keywords. To exclude specific values you can also prefix them with a minus sign (`-`). Note: use a `\` in front of it in case you have a minus as part of the substring you're filtering for. The maximum number of different keywords to combine in a parameter is 50. **Examples**: - **Search for multiple keywords**: `https://jobdataapi.com/api/jobs/?company_specialty=web|OR|dev|OR|design` This query retrieves jobs where the company's specialty includes **web**, **dev**, or **design**. - **Exclude specific keywords**: `https://jobdataapi.com/api/jobs/?company_name=-baz|OR|-bar|OR|-foo` This query excludes companies with names containing **baz**, **bar**, or **foo**. - **Combine inclusion and exclusion**: `https://jobdataapi.com/api/jobs/?title=designer|OR|artist|OR|-ux|OR|-ui` This query retrieves jobs with **designer** or **artist** in their title but excludes any of those that contain either **ux** or **ui**. ## Use Cases ### 1. Geographic Filtering Use multi-code parameters to filter jobs or companies by specific regions, countries, or states. **Example**: ```bash https://jobdataapi.com/api/jobs/?country_code=DE|CH|AT ``` This query retrieves jobs from Germany (`DE`), Switzerland (`CH`), and Austria (`AT`). ### 2. Job Type Filtering Use multi-ID parameters to filter jobs by multiple job types. **Example**: ```bash https://jobdataapi.com/api/jobs/?type_id=1|4 ``` This query retrieves jobs that are either Full Time (`type_id=1`) or Internship (`type_id=4`). ### 3. Company Specialty Filtering Use multi-keyword parameters to filter companies by their specialties. **Example**: ```bash https://jobdataapi.com/api/jobs/?company_specialty=AI|OR|Machine+Learning ``` This query retrieves jobs from companies specializing in AI or Machine Learning. ### 4. Exclusion Filters Use exclusion filters to refine your results by excluding specific values. **Example**: ```bash https://jobdataapi.com/api/jobs/?country_code=-CA|-US ``` This query excludes jobs from Canada (`CA`) and the United States (`US`). ## Advanced Examples ### Combining Multiple Filters You can combine multiple filters to create highly specific queries. For example, you might want to find all **remote** jobs in **Germany** or **Switzerland**, excluding internships. **Example**: ```bash https://jobdataapi.com/api/jobs/?has_remote=true&country_code=DE|CH&type_id=-4 ``` - `has_remote=true`: Filters for remote jobs. - `country_code=DE|CH`: Includes jobs from Germany and Switzerland. - `type_id=-4`: Excludes internships. ### Keyword Search in Job Titles Use the `title` parameter with multi-keyword support to search for jobs with specific keywords in their titles. **Example**: ```bash https://jobdataapi.com/api/jobs/?title=Software+Engineer|OR|Data+Scientist|OR|-Manage|OR|-Lead|OR|-Staff ``` This query retrieves jobs with titles containing either **Software Engineer** or **Data Scientist** but without any jobs that have titles related to leadershiop or management roles. ### Filtering by Company Attributes You can filter jobs based on specific company attributes, such as company size, founding year, or specialties. **Example**: ```bash https://jobdataapi.com/api/jobs/?company_min_size=51&company_max_size=201&company_founded_after=2010&company_specialty=AI|OR|Machine+Learning ``` - `company_min_size=51`: Filters for companies with at least 51 employees. - `company_max_size=201`: Filters for companies with up to 201 employees. - `company_founded_after=2010`: Filters for companies founded after 2010. - `company_specialty=AI|OR|Machine+Learning`: Filters for companies specializing in AI or Machine Learning. ## Best Practices 1. **Use Specific Filters**: Start with broad filters and gradually narrow down your query using multi-value parameters to avoid overwhelming results. 2. **Combine Inclusion and Exclusion**: Use exclusion (`-`) to refine your results further by removing unwanted data. 3. **Test Queries**: Test your queries with a small dataset (e.g., `page_size=10`) to ensure they return the expected results before scaling up. 4. **Leverage `|OR|` for Keywords**: Use the `|OR|` operator for multi-keyword searches to capture a wider range of relevant results. ## Troubleshooting ### No Results Returned - Ensure that the parameter names and values are correct. - Check for typos in keywords or codes. - Verify that the API key is valid and included in the request. ### Unexpected Results - Double-check the use of `|OR|` and exclusion (`-`) operators. - Test individual filters separately to isolate the issue. ### Large Result Sets - Use pagination (`page` and `page_size`) to manage large datasets. - Apply additional filters to narrow down the results. ## Conclusion Multi-value parameters provide a powerful way to refine your queries and retrieve highly specific job and company data. By combining inclusion, exclusion, and keyword operators, you can create flexible and efficient searches tailored to your needs. Whether you're building a job search platform, conducting market research, or analyzing hiring trends, these features will help you get the most out of our jobdata API. # Vector Embeddings and Search API Documentation Enhance job searches with semantic understanding through vector embeddings. Source: https://jobdataapi.com/c/vector-embeddings-and-search-api-documentation/index.md --- ## Introduction The jobdata API provides **vector embeddings** and **vector search** capabilities, enabling advanced job search functionalities. These features allow users to leverage pre-generated embeddings for job posts and perform semantic searches to find job listings that are contextually similar to a given query. This is particularly useful for job search platforms, HR software, and market researchers who need to match job postings based on semantic meaning rather than just keyword matching. Vector embeddings are numerical representations of text that capture the semantic meaning of the content. By using embeddings, the API can understand the context and meaning behind job descriptions, titles, and other text fields, allowing for more accurate and relevant search results. ## Limitations This service is still in an experimental phase. We try our best to provide a production ready and reliable experience at all times. It's also important to keep in mind that we're dependent on a single 3rd-party provider here (OpenAI in this case for generating vector embeddings through their [`text-embedding-3-small` model](https://platform.openai.com/docs/guides/embeddings)) for the supply of all embeddings data. In the event of a permanent disruption or disappearance of their service offering we'd switch to an open source/weights alternative (at least similar in performance) and backfill all job listings with newly generated embeddings available to our subscribed customers. ## Privacy (Vector Search) When using the `vec_text` query parameter to perform vector embedding matching through our API, the text value of the parameter is being sent to an OpenAI endpoint for instant embeddings generation. Although we have set [Data retention to *Disabled*](https://platform.openai.com/docs/guides/your-data) and don't store any queries by default on our own, we strongly recommend to not include any sensitive data in your queries and using generic search phrases or anonymized job profiles. ## Endpoint Overview **Endpoint (list):** `/api/jobs/` **Endpoint (single element):** `/api/jobs/{id}/` **Method:** `GET`, `POST` **Authorization Required:** Yes (**access pro+** or higher subscription plans) **Description:** The Jobs endpoint now supports vector embeddings and vector search, allowing users to retrieve job listings with pre-generated embeddings and perform semantic searches based on a text query. ## Main Features ### Vector Embeddings The API now provides pre-generated embeddings for every job post using OpenAI's `text-embedding-3-small` model. These embeddings are available as half-precision floats at 768 dimensions: - **768-dimensional embeddings in half-precision** (`embed_3sh`): These embeddings capture a representation of the job post's title and description, suitable for detailed semantic analysis. To activate them in the API response, you can use the following query parameter: - **embed_3sh**: Set to `true` to include embeddings in the response. Note: With OpenAI's text-embedding-3-small model you can [shorten embeddings](https://arxiv.org/abs/2205.13147) (i.e. remove some numbers from the end of the sequence) without the embedding losing its concept-representing properties. ### Vector Search The API now supports **vector search**, which allows you to find job listings that are semantically similar to a given text query. This is done by converting the query into embeddings in real-time and comparing it against the pre-generated embeddings of job posts using cosine similarity. - **vec_text**: This query parameter allows you to specify a text string (up to 1000 characters) for vector search. The API will return job listings that are most similar to the query based on their embeddings. - **vec_embedding** (POST only): Matches jobs against a given array of 768 floats representing a 768-dimensional embedding in half-precision generated with OpenAI's `text-embedding-3-small` model. Note that you can only use either `vec_text` or `vec_embedding` at the same time, if both are present `vec_embedding` is being matched against and `vec_text` will be ignored. This is also the only value accepted during a POST submission, all other parameters need to be submitted as URL parameters. - **max_dist**: Definies the maximum value for the cosine distance to be applied during vector similarity search. Must be a value between `0.1 - 0.9` Note that **searches are case-sensitive** (even punctuation can make a difference!), meaning the casing of your query can influence the semantic meaning and the results returned. For example, a search for "Software Engineer" may yield different results compared to "software engineer" due to variations in how the model interprets the context. To ensure consistent and accurate results, consider standardizing the casing of your search queries before making API requests. This is particularly relevant when searching for job titles, technical terms, or industry-specific phrases. ### Cosine Similarity Threshold The API uses a default cosine similarity threshold of **0.5** to filter out job posts that are not sufficiently similar to the query. This ensures that only relevant job listings are returned. You can use the `max_dist` parameter to adjust this value. When using **vector search** (`vec_text` or `vec_embedding`), a `cosine_dist` field (float) is added to each job listing in the response, indicating the cosine similarity distance between the query and the job post. This value helps you gauge the relevance of each result, with lower values representing higher semantic similarity to your search query. The results are automatically ordered by `cosine_dist`, ensuring that the most semantically similar job listings appear first, followed by those with progressively lower similarity. ### Combining Vector Search with Other Filters You can seamlessly combine a vector search query with our existing search and filter parameters available on the `/api/jobs/` endpoint. This allows you to refine your semantic search results using additional criteria such as location, job type, experience level, salary range, and more. For example, you can perform a vector search for "remote software engineer with AI experience" while filtering by country, salary range, or job type to narrow down the results. This combination of semantic understanding and precise filtering ensures that you receive the most relevant and targeted job listings for your specific needs. ## Request To make use of the new vector embeddings and search features, you can include the relevant query parameters in your request. Below are examples of how to make requests using `curl` and Python. ### Using curl #### Retrieve Job Listings with Embeddings ```bash curl -X GET "https://jobdataapi.com/api/jobs/?embed_3sh=true" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` #### Perform Vector Search ```bash curl -X GET "https://jobdataapi.com/api/jobs/?vec_text=remote%20software%20engineer%20with%20AI%20experience" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Using Python #### Retrieve Job Listings with Embeddings ```python import requests url = "https://jobdataapi.com/api/jobs/" params = { "embed_3sh": True, } headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers, params=params) print(response.json()) ``` #### Perform Vector Search ```python import requests url = "https://jobdataapi.com/api/jobs/" params = { "vec_text": "remote software engineer with AI experience" } headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers, params=params) print(response.json()) ``` ### Using `vec_embedding` via POST request for matching ```python import requests url = "https://jobdataapi.com/api/jobs/" headers = {"Authorization": "Api-Key YOUR_API_KEY"} # Example embedding (768 floats, shortened for readability) embedding = [ -0.06494140625, 0.04852294921875, 0.070068359375, 0.024200439453125, -0.032379150390625, 0.044189453125, ... ] params = { "max_dist": 0.45, # cosine distance threshold "country": "US", # you can still combine with filters } payload = { "vec_embedding": embedding } response = requests.post(url, headers=headers, params=params, json=payload) print(response.json()) ``` **Important notes**: * `vec_embedding` must be exactly 768 floats (half-precision vector from `text-embedding-3-small`, e.g. `embed_3sh` values from jobs already fetched from the API). * params go in the URL (e.g., max_dist, country, etc.). * The POST body (json) only contains `vec_embedding`. ## Response When vector embeddings are activated, the response will include additional field for each job listing: - **embedding_3sh**: A 768-dimensional, half-precision floats vector embedding of the job post (title + description). ### Example Response with Embeddings ```json { "count": 2, "next": null, "previous": null, "results": [ { "id": 12345, "company": { "name": "Tech Innovations Inc.", "logo": "https://example.com/logo.png", "website_url": "https://techinnovations.com", "linkedin_url": "https://linkedin.com/company/tech-innovations-inc", ... }, "title": "Senior Software Engineer", "location": "Remote", "has_remote": true, "published": "2024-02-01", "description": "We are looking for a Senior Software Engineer...", "experience_level": "SE", "application_url": "https://techinnovations.com/careers/12345", "salary_min": "100000", "salary_max": "150000", "salary_currency": "USD", "embedding_3sh": [0.123, 0.456, 0.789, ...], // 768-dimensional half-precision embedding }, // Additional job listings... ] } ``` ### Example Response for Vector Search ```json { "count": 3, "next": null, "previous": null, "results": [ { "id": 12345, "company": { "name": "Tech Innovations Inc.", "logo": "https://example.com/logo.png", "website_url": "https://techinnovations.com", "linkedin_url": "https://linkedin.com/company/tech-innovations-inc", ... }, "title": "Senior Software Engineer", "location": "Remote", "has_remote": true, "published": "2024-02-01", "description": "We are looking for a Senior Software Engineer with experience in AI...", "experience_level": "SE", "application_url": "https://techinnovations.com/careers/12345", "salary_min": "100000", "salary_max": "150000", "salary_currency": "USD" "cosine_dist": 0.36391339790563 }, { "id": 67890, "company": { "name": "AI Solutions Ltd.", "logo": "https://example.com/logo.png", "website_url": "https://aisolutions.com", "linkedin_url": "https://linkedin.com/company/ai-solutions-ltd", ... }, "title": "AI Engineer", "location": "Remote", "has_remote": true, "published": "2024-02-01", "description": "We are hiring an AI Engineer to work on cutting-edge machine learning projects...", "experience_level": "MI", "application_url": "https://aisolutions.com/careers/67890", "salary_min": "90000", "salary_max": "120000", "salary_currency": "USD", "cosine_dist": 0.396054643510141 }, // Additional job listings... ] } ``` ## Use Cases ### Semantic Job Search Vector search allows you to find job listings that are semantically similar to their query, even if the exact keywords are not present in the job description. For example, a search for "remote software engineer with AI experience" could return job posts that mention "machine learning," "data science," or "artificial intelligence," even if those exact terms are not used. ### Improved Matching Algorithms HR and talent platforms can leverage vector search to find candidates whose profiles closely match the requirements of job postings. This can significantly enhance the recruitment process by identifying suitable candidates more efficiently. ### Market Analysis Researchers can use vector embeddings to analyze job market trends by clustering job postings based on their semantic content. This can provide insights into emerging skills, industries, and job roles. ### Personalized Job Recommendations Job search platforms can use vector embeddings to provide personalized job recommendations to users based on their search history, preferences, and profile information. This can improve user engagement and satisfaction. ## Notes - **Access Requirements**: Vector embeddings and vector search features are available only with **access pro+** and **access ultra** subscriptions. - **Rate Limits**: The API currently allows a limited set of generative vector search queries per day depending on the API access plan you subscribed to. - **Embeddings Processing Time**: Generating embeddings for new job posts may take up to a few hours to process and become available. If you enable the `embed_3sh` parameter or use `vec_text`/`vec_embedding`, job listings that have not yet completed the embedding generation process will be excluded from the results. This ensures that only jobs with fully processed embeddings are returned. If you encounter missing jobs, try your request again after a short delay to allow the embeddings to be generated. - **Vector Search vs. Full-Text Search**: While vector search provides powerful semantic matching capabilities, it is not a replacement for full-text or other search and filtering methods. Full-text search remains essential for precise keyword-based queries, such as searching for exact phrases or specific terms. Vector search excels at understanding context and meaning, making it ideal for broader, concept-based queries, but it may not always capture exact matches or highly specific criteria. ## Conclusion By leveraging these features, you can perform more accurate and context-aware searches, match job postings with candidate profiles, and gain deeper insights into job market trends. Whether you're building a job search platform, conducting market research, or developing HR solutions, these capabilities will enhance your ability to deliver relevant and meaningful results. With pre-generated embeddings and built-in vector search, there’s no need for subscribed customers to roll their own infrastructure to generate embeddings for every job post. We handle all the complexity, allowing you to focus on delivering value to your users. # Industries API Endpoint Documentation A list of industries available for company search. Source: https://jobdataapi.com/c/industries-api-endpoint-documentation/index.md --- ## Introduction The jobdata API's Industries endpoint serves as a beacon for those seeking to explore opportunities across a diverse range of sectors. This documentation section delves deep into the functionalities and usage of the Industries endpoint, providing you with a comprehensive guide to harnessing industry-specific job data effectively. ## Endpoint Overview **Endpoint (list):** `/api/industries/` **Endpoint (single element):** `/api/industries/{id}/` **Method:** `GET` **Authorization Required:** Yes **Description:** The Industries endpoint is a vital resource for accessing a list of all industries recognized within the jobdata API ecosystem. This data is crucial for users aiming to categorize job listings or search for opportunities within specific sectors. Whether you're a job platform seeking to offer filtered searches or a researcher analyzing job market trends, understanding the landscape of industries is essential. ## Request Methods To interact with the Industries endpoint, you must include an authorization header with your API key. Below are examples of how to make a request using both `curl` and Python, two common tools for API interactions. ### Using curl ```bash curl -X GET "https://jobdataapi.com/api/industries/" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Using Python ```python import requests url = "https://jobdataapi.com/api/industries/" headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers) print(response.json()) ``` ## Parameters The Industries endpoint is straightforward and does not require any query parameters. The only prerequisite for access is the inclusion of a valid API key in the authorization header. ## Response Structure Upon a successful request, the API returns a JSON object containing an array of industries. Each industry is represented with a unique identifier and a name that describes the sector. This structured response allows for easy integration and manipulation within your applications. ### Example Response ```json [ {"id":22,"name":"Accounting"}, {"id":8,"name":"Advertising Services"}, {"id":245,"name":"Agricultural Chemical Manufacturing"}, {"id":189,"name":"Agriculture, Construction, Mining Machinery Manufacturing"}, {"id":56,"name":"Airlines and Aviation"}, {"id":219,"name":"Alternative Medicine"}, {"id":241,"name":"Animation"}, // Additional industries omitted for brevity ] ``` ## Use Cases - **Job Search Platforms:** Incorporate industry data to enhance search functionality, enabling users to filter job listings by their preferred sector. - **Market Research:** Analysts and researchers can leverage industry information to study employment trends, sector growth, and workforce distribution. - **Career Advisory Services:** Career coaches and advisory platforms can use detailed industry data to guide job seekers towards industries that match their skills and interests. - **Business Planning:** Companies looking to expand or diversify can analyze job market data across different industries to make informed decisions. ## Notes - Ensure to replace `YOUR_API_KEY` with your actual jobdata API key in the authorization header. - The job market is dynamic, with new industries emerging and others evolving. Regularly check the Industries endpoint for the most up-to-date information. The Industries endpoint of the jobdata API is an invaluable resource for anyone looking to gain insights into the job market's industry-specific dynamics. By providing detailed and structured industry data, it opens up numerous possibilities for job search platforms, market research, and career guidance. # Company Types API Endpoint Documentation A list of company types available for company search. Source: https://jobdataapi.com/c/company-types-api-endpoint-documentation/index.md --- ## Introduction The Company Types endpoint in the jobdata API serves as a resource for identifying and categorizing companies based on their type, such as public, private, nonprofit, or educational. This categorization is instrumental for users aiming to filter job listings or company searches according to the nature of the organization's ownership or operational model. It enables a more tailored approach to job searches, company research, and market analysis by offering insights into the structural makeup of companies listed within the jobdata API database. ## Endpoint Overview **Endpoint (list):** `/api/companytypes/` **Endpoint (single element):** `/api/companytypes/{id}/` **Method:** `GET` **Authorization Required:** Yes **Description:** This endpoint provides a list of all company types available within the jobdata API database. It is designed to help users understand the various categories of companies, such as public, private, governmental, or nonprofit, facilitating more nuanced searches and analyses. ## Request Accessing the Company Types endpoint requires an API key for authorization. Below are examples demonstrating how to make a request to this endpoint using `curl` and Python. ### Using curl ```bash curl -X GET "https://jobdataapi.com/api/companytypes/" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Using Python ```python import requests url = "https://jobdataapi.com/api/companytypes/" headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers) print(response.json()) ``` Replace `YOUR_API_KEY` with your actual jobdata API key in the authorization header to authenticate your request. ## Parameters This endpoint does not require any query parameters. The sole requirement for accessing the data is the authorization header with a valid API key. ## Response Upon a successful request, the endpoint returns a JSON object containing an array of company types. Each entry in the array consists of a unique identifier (`id`) and a name (`name`) that describes the type of company. ### Example Response ```json [ {"id":8,"name":"Educational"}, {"id":2,"name":"Government Agency"}, {"id":3,"name":"Nonprofit"}, {"id":5,"name":"Partnership"}, {"id":1,"name":"Privately Held"}, {"id":4,"name":"Public Company"}, {"id":6,"name":"Self-Employed"}, {"id":7,"name":"Self-Owned"} ] ``` ## Use Cases - **Job Search Platforms:** Facilitate users in filtering job listings by company type, enabling them to apply to companies that align with their preferred organizational structure or values. - **Market Researchers:** Provide a means for analysts to segment and analyze job market trends based on the type of companies hiring, aiding in comprehensive market analysis. - **Business Development:** Assist professionals in identifying potential partners or investment opportunities by filtering companies according to their operational or ownership model. - **Competitive Analysis:** Enable companies to perform competitive analysis by understanding the landscape of other organizations within the same or different company types. ## Notes - An API key is required to access this endpoint. Ensure you have a valid API key included in the authorization header of your request. This documentation section offers a detailed guide on interacting with the Company Types endpoint, equipping developers, researchers, and business professionals with the knowledge to effectively utilize this data in their applications, analyses, and strategic planning. # Companies API Endpoint Documentation Accessing detailed company profiles. Source: https://jobdataapi.com/c/companies-api-endpoint-documentation/index.md --- ## Introduction The Companies endpoint is a powerful feature within the jobdata API that offers comprehensive information about companies that are currently hiring. This endpoint serves as a directory to explore and retrieve detailed company profiles, including their name, logo, website, social media links, description, headquarters location, size, founding year, specialties, industry, and type. It is designed to help job search platforms, HR software, market researchers, and business analysts obtain valuable insights into companies across various industries. ## Endpoint Overview **Endpoint (list):** `/api/companies/` **Endpoint (single element):** `/api/companies/{id}/` **Method:** `GET` for listing companies and `GET` with company ID for retrieving a specific company's details. **Authorization Required:** Yes (**access pro** subscription) **Description:** The Companies endpoint allows users to fetch a list of companies with optional filtering parameters to narrow down the search based on specific criteria, such as industry, company size, and location. Additionally, it provides a detailed view of a single company's profile by specifying the company ID. ## Request Making requests to the Companies endpoint requires an authorization header with your API key. Below are examples of how to make requests using both `curl` and Python for listing companies and retrieving details of a specific company. ### Listing Companies Using curl ```bash curl -X GET "https://jobdataapi.com/api/companies/?industry_id=1&min_size=11&max_size=200" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Listing Companies Using Python ```python import requests url = "https://jobdataapi.com/api/companies/" params = { "industry_id": 79, "min_size": 11, "max_size": 200 } headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers, params=params) print(response.json()) ``` ### Retrieving a Specific Company's Details Using curl ```bash curl -X GET "https://jobdataapi.com/api/companies/123/" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` ### Retrieving a Specific Company's Details Using Python ```python import requests url = "https://jobdataapi.com/api/companies/123/" headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers) print(response.json()) ``` ## Parameters For listing companies, the endpoint supports several query parameters to filter the results (available with an [access pro](/accounts/pricing/) subscription. Some parameters allow for multiple values be set to get even more precise with narrowing down a query. These are indicated by an **[[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]** *=multi-ID*, **[[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]** *=multi-code*, and **[[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]** *=multi-keyword* right behind their parameter name. - **is_agency**: Filter for recruiting/staffing agencies via `is_agency=true` or all other companies (direct hiring) with `false`. By default all companies are shown in the results. - **source_id** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filter companies by their source/ATS ID. - **name** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filter companies by their name or parts of it. - **website** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filter companies by their website URL or domain name. - **description** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filter companies by a search term in their description. - **type_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filter companies by their type ID, such as public, private, or non-profit (see [Company Types endpoint](/c/company-types-api-endpoint-documentation/) for more info). - **specialty** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filter companies by a specific specialty or focus area. - **hq** [[mk](/c/multi-value-parameters-documentation/#multi-keyword-parameters)]: Filter companies by the location of their headquarters. - **hq_region_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filter companies by the ID of the region their headquarters are located in (see [Job Regions endpoint](/c/job-regions-api-endpoint-documentation/) for more info). - **hq_country_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filter companies by the ID of the country their headquarters are located in (see [Job Countries](/c/job-countries-api-endpoint-documentation/) endpoint for more info). - **hq_state_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filter companies by the ID of the state their headquarters are located in (see [Job States](/c/job-states-api-endpoint-documentation/) endpoint for more info). - **hq_city_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filter companies by the ID of the city their headquarters are located in (see [Job Cities](/c/job-cities-api-endpoint-documentation/) endpoint for more info). - **industry_id** [[mi](/c/multi-value-parameters-documentation/#multi-id-and-multi-code-parameters)]: Filter companies by industry ID to match companies in specific industries (see [Industries endpoint](/c/industries-api-endpoint-documentation/) for more info). - **max_size**: Filter companies with a maximum number of employees (see [size range values below](/c/companies-api-endpoint-documentation/#company-size-filtering)). - **min_size**: Filter companies with a minimum number of employees (see [size range values below](/c/companies-api-endpoint-documentation/#company-size-filtering)). - **founded_after**: Filter companies founded after a specific year (`YYYY`). - **founded_before**: Filter companies founded before a specific year (`YYYY`). - **founded_in**: Filter companies founded in a specific year. - **min_jobs_open**: Filter companies by minimum number of open positions. - **min_jobs_total**: Filter companies by minimum number of total positions (including closed/expired). - **page**: Specifies the page number in the paginated result set - requires a valid [access pro](/accounts/pricing/) API key. - **page_size**: Determines the number of results per page (1 - 5000, default: 200) - requires a valid [access pro](/accounts/pricing/) API key. Note that as a **access pro** subscriber many of the above query parameters are also available for the `/api/jobs/` endpoint and can be used for advanced job post filtering - see [Jobs endpoint](/c/jobs-api-endpoint-documentation/#advanced-company-info-parameters) for more info on this feature. ### Example Request with Parameters #### cURL ```bash curl -X GET "https://jobdataapi.com/api/companies/?name=OpenAI&min_size=11&max_size=500&page=1&page_size=250" \ -H "Authorization: Api-Key YOUR_API_KEY" ``` #### Python ```python import requests url = "https://jobdataapi.com/api/companies/" params = { "name": "OpenAI", "min_size": 11, "max_size": 500, "page": 1, "page_size": 250 } headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers, params=params) print(response.json()) ``` ### Company Size Filtering When utilizing the `max_size` and `min_size` parameters to filter companies by their size, it's essential to use specific predefined values. These values correspond to different ranges of employee counts, allowing for precise segmentation of companies based on their size. The valid values and their associated employee count ranges are as follows: - **0** for companies with 0-1 employees - **2** for companies with 2-10 employees - **11** for companies with 11-50 employees - **51** for companies with 51-200 employees - **201** for companies with 201-500 employees - **501** for companies with 501-1,000 employees - **1001** for companies with 1,001-5,000 employees - **5001** for companies with 5,001-10,000 employees - **10001** for companies with more than 10,000 employees To apply these filters, select the appropriate value that matches the size range you're interested in. For instance, to filter for companies that have between 51 to 200 employees, you would specify `min_size=51` and `max_size=200` in your query parameters. ## Response The response is a JSON object containing a list of companies that match the query parameters. Each company in the list includes details such as the company's name, logo, website URL, description, headquarters location, size, founding year, and more. ### Response Data Structure The `companies_list` operation returns a JSON object containing the following main attributes: - **count**: The total number of companies matching the query. - **next**: A URL to the next page of results (pagination). - **previous**: A URL to the previous page of results (pagination). - **results**: An array of company objects, each containing detailed information about a company. Each object in the `results` array includes: - **id**: A unique integer identifier for the company. - **source_id**: An integer identifier for the source/ATS of the company. - **name**: The name of the company. - **logo**: A URL to the company's logo image. - **website_url**: The company's official website URL. - **linkedin_url**: The company's LinkedIn page URL. - **twitter_handle**: The company's Twitter handle. - **github_url**: The company's GitHub page URL. - **is_agency**: A boolean flag that determines if the company is a recruiting/staffing firm or not. - **info_description**: A brief description of the company. - **info_hq**: The location of the company's headquarters. - **info_hq_string**: A GeoNames-optimized location of the company's headquarters (derived from the original `info_hq` field content). - **info_hq_region**: The ID of the region the company headquarters are located in. - **info_hq_country**: The ID of the country the company headquarters are located in. - **info_hq_state**: The ID of the state the company headquarters are located in. - **info_hq_city**: The ID of the city the company headquarters are located in. - **info_size**: The size of the company in terms of number of employees. - **info_founded**: The year the company was founded. - **info_specialties**: Specialties or areas of focus for the company. - **info_industry**: An object representing the industry the company operates in, including an `id` and `name`. - **info_type**: An object representing the type of company, including an `id` and `name`. - **num_jobs_open**: The number of open/live jobs (updated every 2h). - **num_jobs_total**: The number of overall/total jobs (updated every 2h). ### Example Response ```json { "count": 1, "next": null, "previous": null, "results": [ { "id": 123, "source_id": 13, "name": "OpenAI", "logo": "https://example.com/logo.png", "website_url": "https://openai.com", "linkedin_url": "https://linkedin.com/company/openai", "twitter_handle": "openai", "github_url": "https://github.com/openai", "info_description": "OpenAI is an AI research and deployment company dedicated to ensuring that general-purpose artificial intelligence benefits all of humanity...", "info_hq": "San Francisco, CA", "info_hq_string": "San Francisco, California, United States", "info_hq_region": { "id":5, "name":"North America" }, "info_hq_country": { "id":238, "code":"US", ... }, "info_hq_state" { "geonameid": 5332921, "code":"CA", ... }, "info_hq_city": { "geonameid":5391959, "asciiname":"San Francisco", "name":"San Francisco", ... }, "info_size": 201, "info_founded": 2015, "info_specialties": "artificial intelligence and machine learning", "info_industry": { "id": 79, "name": "Research Services" }, "info_type": { "id": 5, "name": "Partnership" }, "num_jobs_open":135, "num_jobs_total":326 } ] } ``` ## Use Cases - **Job Search Platforms:** Enhance job listings by providing detailed company profiles alongside job ads. - **HR Software:** Offer in-depth insights into companies for users researching potential employers. - **Market Researchers:** Analyze company data across industries, sizes, and locations for market analysis. - **Business Analysts:** Obtain a comprehensive overview of companies for competitive analysis and business strategy planning. ## Notes - Replace `YOUR_API_KEY` with your actual jobdata API key in the header. - The addition of enhanced company information may be delayed by a few weeks after a company first appears in the database. So it is advised to check and update locally stored company info regularly, e.g. on a monthly basis. - This endpoint is available to **access pro** subscribers only. - The detailed information provided by this endpoint can greatly enhance the value of job listings and company research tools. This section offers a complete guide on how to interact with the Companies endpoint, ensuring that developers and businesses can effectively utilize this information to enhance their applications and services. # Currency Rates API Endpoint Documentation Accessing historical and current foreign exchange rates for salary conversion and analysis. Source: https://jobdataapi.com/c/currency-rates-api-endpoint-documentation/index.md --- ## Introduction The Currency Rates endpoint in the jobdata API provides access to daily exchange rates for a wide range of global currencies. The data is sourced from [Frankfurter](https://frankfurter.dev/), a reliable and widely used foreign exchange data provider. This endpoint is available to all plans, including public access, making it a valuable resource for applications that need currency conversion rates or historical currency comparisons. Internally, jobdata uses this same currency rate data to normalize all salary values to both **USD** and **EUR**. This allows for consistent salary filtering across jobs in different currencies. ## Endpoint Overview **Endpoint (list):** `/api/currencyrates/` **Method:** `GET` **Authorization Required:** Yes **Description:** The Currency Rates endpoint returns daily exchange rates for multiple currencies, with each record containing the date and a mapping of currency codes to their values against other currencies. Results can be filtered by date or date ranges, enabling retrieval of historical currency rate data. ## Request This endpoint can be accessed without authentication. Below are examples of making requests using both `curl` and Python. ### Listing Currency Rates Using curl ```bash curl -X GET "https://jobdataapi.com/api/currencyrates/?date=2025-08-11" ``` ### Listing Currency Rates Using Python ```python import requests url = "https://jobdataapi.com/api/currencyrates/" params = { "date": "2025-08-11" } response = requests.get(url, params=params) print(response.json()) ``` ## Parameters The Currency Rates endpoint supports the following filters: * **date**: Retrieve exchange rates for a specific date in `YYYY-MM-DD` format. Example: `date=2025-08-11` * **date\_from**: Retrieve rates from a starting date onward (inclusive). Example: `date_from=2025-08-01` * **date\_to**: Retrieve rates up to a specific date (inclusive). Example: `date_to=2025-08-10` * **page**: Specifies the page number in the paginated result set. * **page\_size**: Determines the number of results per page (1 – 5000, default: 200). ### Example Request with Parameters #### cURL ```bash curl -X GET "https://jobdataapi.com/api/currencyrates/?date_from=2025-08-01&date_to=2025-08-11&page=1&page_size=100" ``` #### Python ```python import requests url = "https://jobdataapi.com/api/currencyrates/" params = { "date_from": "2025-08-01", "date_to": "2025-08-11", "page": 1, "page_size": 100 } response = requests.get(url, params=params) print(response.json()) ``` ## Response The response is a JSON object containing the total count, pagination links, and an array of daily exchange rate objects. ### Response Data Structure * **count**: Total number of daily rate records matching the query. * **next**: URL to the next page of results (pagination). * **previous**: URL to the previous page of results (pagination). * **results**: An array of rate objects, each with: * **date**: Date of the rates (string, `YYYY-MM-DD`). * **values**: A nested object where each key is a currency code (e.g., `USD`, `EUR`) and the value is another object mapping target currencies to their rates. ### Example Response ```json { "count": 954, "next": "https://jobdataapi.com/api/currencyrates/?page=2", "previous": null, "results": [ { "date": "2025-08-11", "values": { "AUD": {"EUR": 1.7857, "USD": 1.5331}, "BGN": {"EUR": 1.9558, "USD": 1.6791}, "USD": {"EUR": 1.1648}, "EUR": {"USD": 0.85852}, ... } } ] } ``` ## Conversion Examples The `values` object shows conversion rates from a **base currency** to one or more **target currencies**. For example: * `"AUD": {"EUR": 1.7857, "USD": 1.5331}` means **1 AUD = 1.7857 EUR** and **1 AUD = 1.5331 USD**. ### Example 1 — EUR to USD If the `values` include `"EUR": {"USD": 0.85852}`, then: ``` 1 EUR = 0.85852 USD 10 EUR = 10 × 0.85852 = 8.5852 USD ``` ### Example 2 — USD to EUR If `"USD": {"EUR": 1.1648}`, then: ``` 1 USD = 1.1648 EUR 50 USD = 50 × 1.1648 = 58.24 EUR ``` ### Example 3 — Converting Between Two Currencies Without Direct Rate If the direct conversion is not listed, you can **use EUR as an intermediary** (or any common currency): Example: Converting **100 CAD to AUD** Given: ``` CAD → EUR = 1.6003 AUD → EUR = 1.7857 ``` First, convert CAD to EUR: ``` 100 CAD × 1.6003 = 160.03 EUR ``` Then convert EUR to AUD (inverse of AUD → EUR): ``` 1 AUD = 1.7857 EUR 1 EUR = 1 / 1.7857 = 0.5600 AUD 160.03 EUR × 0.5600 = 89.62 AUD ``` ## Python Helper Function for Currency Conversion ```python def convert_currency(values, from_currency, to_currency, amount): from_currency = from_currency.upper() to_currency = to_currency.upper() # Direct conversion available if from_currency in values and to_currency in values[from_currency]: return amount * values[from_currency][to_currency] # Try reverse conversion if available if to_currency in values and from_currency in values[to_currency]: return amount / values[to_currency][from_currency] # Use EUR as intermediary if needed if from_currency != "EUR" and to_currency != "EUR": if from_currency in values and "EUR" in values[from_currency] \ and to_currency in values and "EUR" in values[to_currency]: eur_amount = amount * values[from_currency]["EUR"] return eur_amount / values[to_currency]["EUR"] raise ValueError(f"Conversion from {from_currency} to {to_currency} not available.") # Example usage values = { "AUD": {"EUR": 1.7857, "USD": 1.5331}, "USD": {"EUR": 1.1648}, "EUR": {"USD": 0.85852} } print(f"50 AUD = {convert_currency(values, 'AUD', 'USD', 50):.2f} USD") ``` ## Supported Currencies The following currency codes are supported for this endpoint: `AUD`, `BGN`, `BRL`, `CAD`, `CHF`, `CNY`, `CZK`, `DKK`, `EUR`, `GBP`, `HKD`, `HUF`, `IDR`, `ILS`, `INR`, `ISK`, `JPY`, `KRW`, `MXN`, `MYR`, `NOK`, `NZD`, `PHP`, `PLN`, `RON`, `SEK`, `SGD`, `THB`, `TRY`, `USD`, `ZAR` ## Use Cases * **Data Analysis:** Perform historical trend analysis or correlation studies using daily rates. * **Job Search Filtering:** Normalize all salary values to USD/EUR for accurate cross-currency job filtering. ## Notes * Data comes from the [Frankfurter API](https://frankfurter.dev/) and is updated about every 8 hours. * All values are floating-point numbers representing the amount of target currency equivalent to 1 unit of the base currency. # CSV File Downloads Documentation Full job database download infos and sample files. Source: https://jobdataapi.com/c/csv-file-downloads-documentation/index.md --- ## Introduction The jobdata API **access ultra** and **access ultra+** packages provide a comprehensive solution for accessing and managing job data. With both API and CSV download options, you can integrate up-to-date job and company information into your projects efficiently. Using the data download feature over accessing the API offers several key advantages, particularly for users who need comprehensive datasets for analysis, offline access, or bulk data processing. The CSV file downloads provide a full snapshot of all job data in our database (updated on a weekly basis), ensuring that you have access to all recent information without the need for continuous API calls. This method might be more efficient for large-scale data handling, especially when starting out with a new project and you need a backfill with all our data at once or in a simple non-JSON format. Additionally, data downloads are particularly beneficial for data scientists and analysts who require complete datasets for advanced analytics and reporting, offering a more streamlined and cost-effective solution (no code needed for handling API calls) compared to the incremental data retrieval typically done via API calls. ## Overview The jobdata API **access ultra** package provides extensive data access and download capabilities, including: - Unlimited access to the Jobdata API feed with comprehensive job post backfill and related full company info. - Expired jobs info. - Job description text search. - Advanced company data search. - Job post embeddings and vector search. - Weekly-updated job data CSV file downloads. A fresh export of the latest data happens every Sunday around 1 p.m. UTC. ## Data Download URLs Data download URLs are generated with unique download access keys to maintain privacy and allow programmatic access. Every file represents its API endpoint counterpart with mostly the same attributes that are available through the **access pro+** subscription package. Additional CSV file versions with all job descriptions in Markdown format (instead of the original HTML variant) as well as their pre-generated vector embeddings (see [Vector Embeddings and Search API Documentation](/c/vector-embeddings-and-search-api-documentation/) for more info on this) of the jobs data are also available. This is to keep file sizes as small as possible so you can pick and choose the data you actually need. In addition to that and to maintain all object relationships there are the following tables that reflect many-to-many relations ships between the job table and its counterparts: - `job_job_types.csv`: Contains all applicable job types for every job. - `job_job_cities.csv`: Contains all associated city selections for every job. - `job_job_states.csv`: Contains all state/canton/administrative region data. - `job_job_countries.csv`: Contains all associated country selections for every job. - `job_job_regions.csv`: Contains all associated region selections for every job. Here are the formats for the all download links available: - Industries: `https://jobdataapi.com/download//industries.csv.gz` - Company types: `https://jobdataapi.com/download//company_types.csv.gz` - Companies: `https://jobdataapi.com/download//companies.csv.gz` - Currency rates: `https://jobdataapi.com/download//currency_rates.csv.gz` - Job types: `https://jobdataapi.com/download//job_types.csv.gz` - Job regions: `https://jobdataapi.com/download//job_regions.csv.gz` - Job countries: `https://jobdataapi.com/download//job_countries.csv.gz` - Job states: `https://jobdataapi.com/download//job_states.csv.gz` - Job cities: `https://jobdataapi.com/download//job_cities.csv.gz` - Jobs: `https://jobdataapi.com/download//jobs.csv.gz` - Jobs (descr. as Markdown): `https://jobdataapi.com/download//jobs_md.csv.gz` - Job embeddings only: `https://jobdataapi.com/download//jobs_em.csv.gz` - Job type relations: `https://jobdataapi.com/download//job_job_types.csv.gz` - Job city relations: `https://jobdataapi.com/download//job_job_cities.csv.gz` - Job state relations: `https://jobdataapi.com/download//job_job_states.csv.gz` - Job country relations: `https://jobdataapi.com/download//job_job_countries.csv.gz` - Job region relations: `https://jobdataapi.com/download//job_job_regions.csv.gz` These links are designed for easy integration into automated systems, ensuring that your data remains up-to-date with minimal effort. You get access to them right after subscribing to the **access ultra** package by clicking "Generate new links" from your dashboard. Note that the download access key is always different from your API access key and can only be used as part of your download link URLs. Generating a new download access key always invalidates the previous one and all its associated download URLs become invalid. ### Vector embedding data With the `jobs_em.csv` you get all our pre-generated vector embeddings. Currently that's through [OpenAI's `text-embedding-3-small`](https://platform.openai.com/docs/guides/embeddings) model with 768 dimensions and half-precision floats (read more about it [here](/c/vector-embeddings-and-search-api-documentation/). The download file contains the corresponding job ID and its embedding (field: `embedding_3sh`). The CSV file might contain empty values as embedding data for some listings. This can happen due to a lag in subsequent processing of the latest jobs that have just been imported. ## Sample Files and SQLite Database Demo To help you get started, we provide sample files containing recent information of 100 companies and their most recent 5000 jobs. Additionally, an SQLite database example demonstrates how the data can be reassembled. ### Sample Files The following CSV files are the exact same format that the full data files would be when subscribed, downloadable from your [dashboard](/accounts/dashboard/) under "Download access": - Industries: [industries.csv](/media/data/industries.csv) - Company types: [company_types.csv](/media/data/company_types.csv) - Companies: [companies.csv](/media/data/companies.csv) - Currency rates: [currency_rates.csv](/media/data/currency_rates.csv) - Job types: [job_types.csv](/media/data/job_types.csv) - Job regions: [job_regions.csv](/media/data/job_regions.csv) - Job countries: [job_countries.csv](/media/data/job_countries.csv) - Job states: [job_states.csv](/media/data/job_states.csv) - Job cities: [job_cities.csv](/media/data/job_cities.csv) - Jobs: [jobs.csv](/media/data/jobs.csv) - Jobs (descr. as Markdown): [jobs_md.csv](/media/data/jobs_md.csv) - Job embeddings only: [jobs_em.csv](/media/data/jobs_em.csv) - Job type relations: [job_job_types.csv](/media/data/job_job_types.csv) - Job city relations: [job_job_cities.csv](/media/data/job_job_cities.csv) - Job state relations: [job_job_states.csv](/media/data/job_job_states.csv) - Job country relations: [job_job_countries.csv](/media/data/job_job_countries.csv) - Job region relations: [job_job_regions.csv](/media/data/job_job_regions.csv) For more details on attributes and field types you can also refer to the corresponding [API endpoint documentation](/c/docs/list/). ### SQLite Demo Database A full SQLite3 database filled with the sample data from above CSV files (without the Markdown version and embeddings) can be downloaded here: [demo.sqlite3](https://jobdataapi.com/media/data/demo.sqlite3) ### SQLite Database Schema The example schema for the SQLite database can be found here: [sqlite_demo_schema.sql](/media/data/sqlite_demo_schema.sql) ## Examples Data downloads are particularly beneficial for data scientists and analysts who require complete datasets for advanced analytics and reporting, offering a more streamlined and cost-effective solution compared to the incremental data retrieval typically done via API calls. Here are some simple use cases for the data download feature, along with corresponding code examples: ### Use Case 1: Market Analysis **Objective**: Analyze job market trends to identify high-demand skills and emerging industries. Steps: **1. Download and load data**: ```sh curl -o jobs.csv.gz https://jobdataapi.com/download//jobs.csv.gz curl -o companies.csv.gz https://jobdataapi.com/download//companies.csv.gz gunzip jobs.csv.gz gunzip companies.csv.gz ``` **2. Analyze job postings**: ```python import pandas as pd jobs = pd.read_csv('jobs.csv') companies = pd.read_csv('companies.csv') # Merge jobs with companies to get complete job data job_data = pd.merge(jobs, companies, left_on='company_id', right_on='id') # Identify high-demand skills by counting occurrences in job descriptions skills = ['Python', 'JavaScript', 'SQL', 'Java', 'AWS'] skill_counts = {skill: job_data['description'].str.contains(skill, case=False).sum() for skill in skills} print(skill_counts) ``` **3. Visualize results**: ```python import matplotlib.pyplot as plt plt.bar(skill_counts.keys(), skill_counts.values()) plt.xlabel('Skills') plt.ylabel('Demand Count') plt.title('High-Demand Skills in Job Postings') plt.show() ``` ### Use Case 2: Competitive Analysis **Objective**: Analyze competitors' hiring patterns and job distribution. Steps: **1. Download and load data**: ```sh curl -o jobs.csv.gz https://jobdataapi.com/download//jobs.csv.gz curl -o companies.csv.gz https://jobdataapi.com/download//companies.csv.gz gunzip jobs.csv.gz gunzip companies.csv.gz ``` **2. Analyze competitor hiring patterns**: ```python import pandas as pd jobs = pd.read_csv('jobs.csv') companies = pd.read_csv('companies.csv') # Filter for competitors' job postings (assuming competitor IDs are known) competitor_ids = [101, 102, 103] # Example competitor IDs competitor_jobs = jobs[jobs['company_id'].isin(competitor_ids)] # Count job postings by competitor competitor_counts = competitor_jobs['company_id'].value_counts() # Map company names for better readability company_names = companies.set_index('id')['name'].to_dict() competitor_counts.index = competitor_counts.index.map(company_names) print(competitor_counts) ``` **3. Visualize results**: ```python import matplotlib.pyplot as plt competitor_counts.plot(kind='bar') plt.xlabel('Competitor') plt.ylabel('Number of Job Postings') plt.title('Competitor Hiring Patterns') plt.show() ``` ### Use Case 3: Salary Analysis **Objective**: Analyze salary distributions across different job titles and industries. Steps: **1. Download and load data**: ```sh curl -o jobs.csv.gz https://jobdataapi.com/download//jobs.csv.gz gunzip jobs.csv.gz ``` **2. Analyze salary data**: ```python import pandas as pd jobs = pd.read_csv('jobs.csv') # Filter out jobs with missing salary information salary_data = jobs.dropna(subset=['salary_min', 'salary_max']) # Calculate average salary salary_data['average_salary'] = (salary_data['salary_min'] + salary_data['salary_max']) / 2 # Analyze by job title title_salary = salary_data.groupby('title')['average_salary'].mean().sort_values(ascending=False) print(title_salary.head(10)) # Top 10 job titles by average salary ``` **3. Visualize results**: ```python import matplotlib.pyplot as plt title_salary.head(10).plot(kind='bar') plt.xlabel('Job Title') plt.ylabel('Average Salary') plt.title('Top 10 Job Titles by Average Salary') plt.show() ``` ### Use Case 4: Job Posting Trends Over Time **Objective**: Analyze trends in job postings over time to identify seasonal patterns and growth areas. Steps: **1. Download and load data**: ```sh curl -o jobs.csv.gz https://jobdataapi.com/download//jobs.csv.gz gunzip jobs.csv.gz ``` **2. Analyze job posting trends**: ```python import pandas as pd jobs = pd.read_csv('jobs.csv') # Convert published date to datetime jobs['published'] = pd.to_datetime(jobs['published']) # Group by month and count job postings monthly_trends = jobs.groupby(jobs['published'].dt.to_period('M')).size() print(monthly_trends) ``` **3. Visualize results**: ```python import matplotlib.pyplot as plt monthly_trends.plot(kind='line') plt.xlabel('Month') plt.ylabel('Number of Job Postings') plt.title('Job Posting Trends Over Time') plt.show() ``` By leveraging the data download feature, these use cases illustrate how various stakeholders can derive actionable insights from comprehensive job and company datasets, enabling informed decision-making and strategic planning. ### CSV file fields reference Below you can find an overview of all the value fields available in each CVS file. Every field corresponds to its API equivalent and contains the same value as if optained via an API request. #### currency_rates.csv - date: Date of the rates (string, YYYY-MM-DD). - values: A nested object where each key is a currency code (e.g., USD, EUR) and the value is another object mapping target currencies to their rates. #### industries.csv - id: Unique industry identifier. - name: Industry name. #### company_types.csv - id: Unique type identifier. - name: Type name. #### companies.csv - id: Unique company identifier. - source_id: External/source ATS identifier for the company. - name: Company name. - logo: URL to the company logo. - website_url: Official website URL. - linkedin_url: LinkedIn profile URL. - twitter_handle: Twitter handle. - github_url: GitHub URL. - is_agency: Indicates whether the company is an agency. - info_description: Short description of the company. - info_hq: Headquarters location string. - info_hq_string: Headquarters location string (normalized form). - info_hq_region_id: HQ region identifier. - info_hq_country_id: HQ country identifier. - info_hq_state_id: HQ state identifier. - info_hq_city_id: HQ city identifier. - info_size: Company size. - info_founded: Founded year. - info_specialties: A string with a list of the company's specialties. - info_industry_id: Industry ID. - info_type_id: Company type ID. - num_jobs_open: Number of currently open jobs (as of export date). - num_jobs_total: Total number of jobs (as of export date). #### job_regions.csv - id: Region identifier. - name: Region name. #### job_countries.csv - id: Country identifier. - code: ISO country code. - name: Country name. - region_id: Region identifier. #### job_states.csv - geonameid: Geoname ID. - code: State code. - asciiname: ASCII name. - name: State name. - country_id: Country identifier. #### job_cities.csv - geonameid: Geoname ID. - asciiname: ASCII city name. - name: City name. - state_id: State ID. - country_id: Country ID. - timezone: Time zone. - latitude: Latitude. - longitude: Longitude. #### job_types.csv - id: Job type ID. - name: Job type name. #### jobs.csv - id: Unique job identifier. - ext_id: External job identifier. - company_id: ID of the company offering the job. - published: Publication date/time. - expired: Expiration date/time. - title: Job title. - location: Job location. - location_string: Job location (normalized form). - description: Full job description (original HTML version). - application_url: Link to apply. - experience_level: Required experience level. - language: Language code of the language the job post is in. - has_remote: Remote work availability. - salary_min: Minimum yearly salary (FTE). - salary_max: Maximum yearly salary (FTE). - salary_currency: Salary currency code. - salary_min_est: Estimated minimum salary (contains converted salary of original, or estimate if not available). - salary_max_est: Estimated maximum salary (contains converted salary of original, or estimate if not available). - salary_min_usd: Minimum salary in USD (contains converted salary of original, or estimate if not available). - salary_max_usd: Maximum salary in USD (contains converted salary of original, or estimate if not available). - salary_min_eur: Minimum salary in EUR (contains converted salary of original, or estimate if not available). - salary_max_eur: Maximum salary in EUR (contains converted salary of original, or estimate if not available). #### jobs_md.csv - id: Unique job identifier. - ext_id: External job identifier. - company_id: ID of the company offering the job. - published: Publication date/time. - expired: Expiration date/time . - title: Job title. - location: Job location. - location_string: Job location (normalized form). - description_md: Markdown version of the full job description. - application_url: Link to apply. - experience_level: Required experience level. - language: Language code. - has_remote: Remote work availability. - salary_min: Minimum yearly salary (FTE). - salary_max: Maximum yearly salary (FTE). - salary_currency: Salary currency code. - salary_min_est: Estimated minimum salary (contains converted salary of original, or estimate if not available). - salary_max_est: Estimated maximum salary (contains converted salary of original, or estimate if not available). - salary_min_usd: Minimum salary in USD (contains converted salary of original, or estimate if not available). - salary_max_usd: Maximum salary in USD (contains converted salary of original, or estimate if not available). - salary_min_eur: Minimum salary in EUR (contains converted salary of original, or estimate if not available). - salary_max_eur: Maximum salary in EUR (contains converted salary of original, or estimate if not available). #### jobs_em.csv - id: Unique job identifier. - company_id: ID of the company offering the job. - embedding_3sh: 768-dimensional, half-precision vector embedding (array of float values). #### job_job_types.csv - id: Job type identifier. - types: Array of job types associated with the job. #### job_job_cities.csv - id: Job identifier. - cities: List of associated city identifiers for the job. #### job_job_states.csv - id: Job identifier. - states: List of associated state identifiers for the job. #### job_job_countries.csv - id: Job identifier. - countries: List of associated country identifiers for the job. #### job_job_regions.csv - id: Job identifier. - regions: List of associated region identifiers for the job. # Integrating the jobdata API with Excel Unlocking job market insights: How to integrate the jobdata API with Excel for advanced analysis. Source: https://jobdataapi.com/c/integrating-the-jobdata-api-with-excel/index.md --- The jobdata API offers a treasure trove of up-to-date job posting information directly from companies' ATS (Applicant Tracking Systems) and career platforms. This guide is designed to help you bridge the gap between the jobdata API and Excel, allowing you to import and analyze job market data efficiently. Using the jobdata API with Excel involves several steps, including setting up Excel to make HTTP requests (since Excel doesn't natively support REST API calls directly), processing the JSON response, and integrating this data into your Excel workbook. This guide will leverage Power Query, available in Excel 2016 and later versions, to import data from the jobdata API into Excel. Power Query is a powerful data connection technology that enables you to discover, connect, combine, and refine data sources to meet your analysis needs. ## Prerequisites - **Microsoft Excel 2016 or later**: This guide uses features available in Excel 2016 and newer versions. - **jobdata API Key**: You need an API key to authenticate your requests. You can obtain this key by signing up on the [jobdataapi.com](/) platform. ## Step 1: Obtain Your jobdata API Key 1. Sign up or log in to your account on [jobdataapi.com](/accounts/login/). 2. Navigate to the [API section](/accounts/dashboard/) to find or generate your API key. This key will be used to authenticate your requests. ## Step 2: Set Up Power Query to Import Data from the jobdata API 1. **Open Excel** and go to the "Data" tab. 2. Click on "Get Data" > "From Other Sources" > "From Web." 3. In the "From Web" dialog box, you'll be prompted to enter a URL. Here, you'll enter the jobdata API endpoint you wish to call. For example, to list jobs, use `https://jobdataapi.com/api/jobs/`. Append query parameters as needed for your request. 4. Before clicking OK, you need to include your API key for authentication. Click the "Advanced" button and add a new HTTP request header: - In the "Name" field, enter `Authorization`. - In the "Value" field, enter `Api-Key YOUR_API_KEY`, replacing `YOUR_API_KEY` with your actual jobdata API key. 5. Click "OK" to proceed. If prompted, choose "Anonymous" as the authentication method since your API key is included in the headers. ## Step 3: Process the JSON Response in Power Query 1. Once the connection is established, Power Query Editor will open, displaying the JSON returned by the API. 2. You might see the JSON structured in a hierarchical way. Click on the "List" link or use the "Record" buttons to navigate through the JSON structure until you find the array of jobs or the specific data you're interested in. 3. Use the "Into Table" button to convert the list or record into a table format. 4. Expand the columns by clicking the button with two arrows on the column header. Select the fields you wish to include in your Excel sheet. 5. Use the available Power Query tools to further transform or filter your data as needed. ## Step 4: Load Data into Excel 1. Once you have the data structured as you desire, click the "Close & Load" button in the Power Query Editor. 2. The data will now be loaded into your Excel workbook as a new table. ## Step 5: Refreshing the Data - To refresh the data and get the latest updates from the jobdata API, simply right-click on the table in Excel and select "Refresh." ## Additional Tips - **Automate Refresh**: You can automate the data refresh process by setting up scheduled refreshes if you're using Excel with OneDrive or SharePoint. - **Handling Pagination**: If the API supports pagination and you need more data than what is returned in a single request, you might need to create additional queries for subsequent pages and append the data. - **Error Handling**: Be prepared to handle errors or issues with the API call, such as rate limits or data formatting issues. By following these steps, you can effectively use the jobdata API with Excel to import, analyze, and refresh job listing data directly within your Excel workbooks, enabling powerful data analysis and reporting capabilities. # Integrating the jobdata API with n8n Unlock the power of job market analytics by integrating the jobdata API with n8n, transforming complex data into actionable insights. Source: https://jobdataapi.com/c/integrating-the-jobdata-api-with-n8n/index.md --- Integrating the jobdata API with [n8n](https://n8n.io/) enables automated workflows that can fetch, process, and utilize job posting data for various purposes, such as market analysis, job board updates, and HR analytics. n8n is a workflow automation tool that allows you to connect different systems and APIs without writing code. This tutorial will guide you through setting up a workflow in n8n to pull data from the jobdata API and process it for your needs. ## Prerequisites - **n8n setup**: Ensure you have n8n installed and running. You can run n8n locally, on a server, or use the cloud version. - **jobdata API Key**: Obtain your API key by signing up or logging into [API section](/accounts/dashboard/). This key is required to authenticate your API requests. ## Step 1: Create a New Workflow 1. Open n8n and click on the "Create New Workflow" button. 2. Give your workflow a meaningful name related to the jobdata integration, such as "Job Market Analysis." ## Step 2: Configure the HTTP Request Node for jobdata API 1. Drag and drop an "HTTP Request" node from the nodes panel to your workflow canvas. 2. Double-click the node to configure it: - **Authentication**: Set to "Header Auth." - **URL**: Enter the jobdata API endpoint you wish to call, e.g., `https://jobdataapi.com/api/jobs/`. You can append query parameters as needed. - **Headers**: - Key: `Authorization` - Value: `Api-Key YOUR_API_KEY` (replace `YOUR_API_KEY` with your actual jobdata API key). - **Method**: Select "GET" if you're retrieving data. For other actions, choose the method accordingly. 3. Save the node settings. ## Step 3: Add and Configure a Function Node (Optional) If you need to process or filter the API response data: 1. Add a "Function" node to your workflow. 2. Connect it to the HTTP Request node. 3. In the Function node, you can write JavaScript code to manipulate the data. For example, filtering job listings based on a specific criterion. 4. Save the node settings. ## Step 4: Add an Output Node Based on what you want to do with the jobdata API data: - **To save data to a database**: Add a database node (e.g., "PostgreSQL", "MySQL") and configure it to insert the data into your database. - **To send notifications**: Add a notification node (e.g., "Email", "Slack") and configure it to send updates or alerts based on the job data. - **For further processing**: Connect to other nodes as required for your workflow. ## Step 5: Execute and Test Your Workflow 1. Click the "Execute Node" button on each node to test the workflow step-by-step. 2. Once you're satisfied with the configuration and the test results, click the "Execute Workflow" button to run the entire workflow. 3. Monitor the execution and output to ensure data is fetched and processed as expected. ## Step 6: Save and Activate the Workflow - After testing, save your workflow. - Toggle the "Active" switch to schedule or trigger your workflow according to your needs (e.g., at regular intervals, via webhook, etc.). Integrating the jobdata API with n8n can streamline your workflow and enhance data processing capabilities. To ensure a seamless integration and make the most out of your workflow automation, consider the following additional tips: ## Additional Tips ### 1. Use Error Handling Nodes - Implement error handling using the "IF" node or "Error Trigger" node to manage API request failures or unexpected data formats gracefully. This allows you to set up notifications or alternative flows for when something goes wrong, ensuring your workflow remains robust and reliable. ### 2. Leverage Credentials and Environment Variables - Store sensitive information such as your jobdata API key in n8n credentials or environment variables. This enhances security and makes it easier to update your API key without modifying each node where it's used. ### 3. Optimize Workflow Performance - Use the "Split In Batches" node to manage large volumes of data more efficiently. This can prevent timeouts and ensure smoother execution when processing extensive job listings. - Consider limiting the amount of data processed in each workflow run to avoid overwhelming your resources, especially if running n8n on limited hardware. ### 4. Automate and Schedule Workflow Execution - Utilize the "Cron" node to schedule your workflows to run at specific times, ensuring you regularly update your data with the latest job listings from the jobdata API. - For real-time data processing, explore using webhooks as triggers if the jobdata API supports them or if you have intermediate systems that can push updates to n8n. ### 5. Modularize Your Workflows - Break down complex processes into smaller, modular workflows that can be reused or easily maintained. Use the "Execute Workflow" node to call other workflows within your n8n setup, allowing for cleaner organization and scalability. ### 6. Enable Logging and Monitoring - Keep track of your workflow executions and performance by enabling logging within n8n. Consider integrating with external monitoring tools if you're running critical workflows that require immediate attention to failures or slowdowns. ### 7. Stay Updated with API Changes - Regularly check the jobdata API documentation for any updates or changes to endpoints, parameters, or rate limits. Keeping your integration up-to-date ensures continuous access to the data and functionalities you rely on. ### 8. Explore Advanced Data Processing - Utilize n8n's "Function Item" node for advanced data manipulation, allowing you to write custom JavaScript code to process each item in your data individually. This is particularly useful for complex transformations or conditional processing. ## Conclusion By following these tips, you can enhance the efficiency, reliability, and functionality of your n8n workflows that integrate with the jobdata API, unlocking powerful automation capabilities for your job market analysis and related tasks. # Integrating the jobdata API with Make Unlock the power of job market analytics by integrating the jobdata API with Make, transforming complex data into actionable insights. Source: https://jobdataapi.com/c/integrating-the-jobdata-api-with-make/index.md --- Integrating the jobdata API with [Make (formerly Integromat)](https://www.make.com/) empowers you to automate workflows that involve fetching, processing, and using job listing data from thousands of companies. Make's visual interface and powerful modules make it simple to connect the jobdata API to various services and tools, enabling diverse applications such as HR analytics, job board updates, and market trend analysis. This tutorial will guide you through the process of setting up an automated workflow in Make to interact with the jobdata API. ## Prerequisites - **Make account**: Ensure you have an active Make account. You can sign up on their website if you don't have one. - **jobdata API Key**: Sign up or log in to your account on [jobdataapi.com to obtain your API key](/accounts/dashboard/), necessary for authenticating your API requests. ## Step 1: Create a New Scenario 1. Log in to your Make account and click on "Create a new scenario." 2. You will be presented with a vast selection of apps and services. Since we're using a custom API request, search for and select the "HTTP" app to add an HTTP request module. ## Step 2: Configure the HTTP Request Module for jobdata API 1. With the HTTP module added to your scenario, select "Make a request" as the action. 2. Configure the request with the following details: - **URL**: Enter the jobdata API endpoint you wish to call (e.g., `https://jobdataapi.com/api/jobs`). Adjust the URL based on the specific endpoint and query parameters you need. - **Method**: Choose "GET" for retrieving data. For other operations, select the method accordingly. - **Headers**: Add a header to include your API key for authentication. - Name: `Authorization` - Value: `Api-Key YOUR_API_KEY` (replace `YOUR_API_KEY` with the actual API key you obtained from jobdataapi.com). 3. Save the module to apply the configurations. ## Step 3: Process and Use the API Response After configuring the HTTP request: 1. **Parse the JSON Response**: Add a tool for parsing JSON from the response to transform it into a structured format that Make can use in subsequent modules. 2. **Add Further Modules**: Depending on what you want to do with the data, you can add more modules. For example: - To save job listings to a database, add a database module (e.g., MySQL, PostgreSQL) and configure it to insert the data. - To send notifications about new job listings, add an email or messaging app module (e.g., Gmail, Slack) and set it up with the desired message content. ## Step 4: Test and Run Your Scenario 1. Use the "Run once" button to test your scenario and ensure it works as expected. 2. Inspect the output and make any necessary adjustments to the scenario or the modules. ## Step 5: Schedule or Trigger Your Scenario - After testing, you can set up scheduling for your scenario to run at specific intervals automatically or trigger it based on specific conditions using webhooks or other triggers supported by Make. ## Step 6: Activate Your Scenario - Once everything is configured and tested, don't forget to activate your scenario. It will then run according to the schedule or triggers you've set. When integrating the jobdata API with Make for a seamless and efficient automation experience, consider these four additional tips: ## Additional Tips ### 1. Utilize Built-in Make Functions for Data Transformation Make offers a variety of built-in functions and tools that can help you manipulate and transform the data received from the jobdata API. These functions are invaluable for formatting dates, filtering job listings based on specific criteria, or even parsing and restructuring the JSON response to fit your needs better. Familiarizing yourself with these functions can save time and reduce the complexity of your scenarios. ### 2. Implement Error Handling Mechanisms Incorporate error handling mechanisms within your scenarios to manage and respond to API errors or unexpected data issues gracefully. Make allows you to use filters and routers to direct the flow of your scenario based on the success or failure of a module. Utilizing these can help you create fallback processes, such as sending error notifications or attempting a data fetch with different parameters, ensuring your workflow remains robust. ### 3. Optimize API Call Usage Consider caching results when possible or setting up conditional logic that limits API requests to only when necessary. Make's scheduling feature can be adjusted to run your scenarios during off-peak hours or at a frequency that balances timeliness with API usage efficiency. ### 4. Leverage Webhooks for Real-time Data Processing If your use case requires real-time processing of job data, explore the possibility of using webhooks. While the jobdata API may not directly support webhook callbacks, you can often set up intermediary solutions that trigger your Make scenario when new data is available. This approach is particularly useful for real-time alerts, job board updates, or immediate analysis and can significantly enhance the responsiveness of your applications. ## Conclusion By following these steps, you can automate the process of fetching and processing job listing data from the jobdata API using Make. This integration can significantly enhance your capabilities in analyzing job market trends, updating job boards, or enriching HR analytics processes, all within a visually intuitive and powerful automation platform. # Integrating the jobdata API with Zapier Simplify your workflow, from HR analytics to job board updates, with easy automation that turns real-time data into actionable insights — no coding required. Source: https://jobdataapi.com/c/integrating-the-jobdata-api-with-zapier/index.md --- Integrating the jobdata API with [Zapier](https://zapier.com/) allows you to automate workflows between jobdata and thousands of other applications, enabling efficient data processing and utilization for various purposes such as HR analytics, job board synchronization, and market trend analysis. Zapier's no-code platform facilitates easy automation, making it accessible for users of all technical levels to connect their favorite apps and services without writing a single line of code. This tutorial will guide you through setting up a Zap (Zapier's term for automated workflows) that interacts with the jobdata API. ## Prerequisites - **Zapier Account**: Ensure you have an active Zapier account. Sign up on their website if you don't have one. - **jobdata API Key**: Obtain your API key by signing up or logging into [your account on jobdataapi.com](/accounts/dashboard/). This key is required to authenticate your requests with the jobdata API. ## Step 1: Create a New Zap 1. Log in to your Zapier account and click the "Create Zap" button. 2. Start by naming your Zap something descriptive, such as "Fetch Job Listings from jobdata API". ## Step 2: Set Up Your Trigger Since Zapier does not have a direct integration with jobdata API, we'll use a Webhooks by Zapier trigger to make a custom request. 1. For the trigger app, search for and select "Webhooks by Zapier". 2. Choose "Catch Hook" as the trigger event and click "Continue". 3. You don't need to enter anything in the "Custom Webhook URL" field, as you're making an outgoing API request. Click "Continue" to proceed. 4. Skip the "Pick off a Child Key" step unless you specifically need to capture data from a nested JSON object. 5. Test the trigger to ensure it's set up correctly. Since this is an outgoing request, this step can also be skipped. ## Step 3: Configure the Webhooks Action for jobdata API 1. Now, add an action step by clicking the "+" button below your trigger setup. 2. Search for and select "Webhooks by Zapier" again, but this time choose "Custom Request" as the action event. 3. Configure the Webhooks action with the following settings: - **Method**: Select "GET" since you're retrieving data from the jobdata API. - **URL**: Enter the jobdata API endpoint you wish to call, e.g., `https://jobdataapi.com/api/jobs/`. Append any necessary query parameters. - **Headers**: Add a header to authenticate your request. - Key: `Authorization` - Value: `Api-Key YOUR_API_KEY`, replacing `YOUR_API_KEY` with the actual API key from your jobdata account. - Leave other fields as default or adjust them according to your specific requirements. 4. Click "Continue" and test your action to ensure it fetches data from the jobdata API successfully. ## Step 4: Process and Utilize the Data After fetching data from the jobdata API, you can add additional steps in your Zap to process or utilize this data: - **Filtering**: Use the Filter by Zapier app to process only job listings that meet certain criteria, like a specific location or industry. - **Database Entry**: Add an action to insert the job listing data into a database, such as Google Sheets, MySQL, or Airtable. - **Notifications**: Set up notifications via email, Slack, or another messaging service to alert you of new job listings that match your criteria. ## Step 5: Test and Activate Your Zap 1. After setting up all your action steps, test the entire Zap to ensure it runs as expected. Zapier will guide you through testing each step. 2. Once you're satisfied with the setup and the tests pass successfully, turn on your Zap. ## Step 6: Monitor and Maintain Your Zap - Zapier provides monitoring tools to track the activity and performance of your Zaps. Use these tools to troubleshoot any issues and ensure your Zap is running smoothly. - Keep an eye on any updates from the jobdata API that might require adjustments to your Zap, such as changes in endpoints, parameters, or authentication methods. ## Additional Tips To ensure a seamless integration of the jobdata API with Zapier and enhance the efficiency and reliability of your automated workflows, consider these three additional tips: ### 1. Optimize Your Zap Performance - **Rate Limits**: Be mindful of Zapier's task limits. Design your Zaps to minimize unnecessary API calls. Utilize Zapier's built-in tools like filters and paths to ensure that your Zaps only proceed under specific conditions, reducing the number of tasks used. - **Data Processing**: For complex data manipulation that might not be directly supported by Zapier's built-in functions, consider using Code by Zapier or integrating with external services like Google Sheets or Airtable for advanced data processing. This can be particularly useful for parsing and transforming job listing data before using it in subsequent steps. ### 2. Regularly Review and Maintain Your Zaps - **Monitor Zap Performance**: Zapier provides logs and performance insights for your Zaps. Regularly review these to identify any errors or inefficiencies. Pay attention to any notifications from Zapier regarding failures or alerts. - **Update and Test After Changes**: If there are updates to the jobdata API (such as changes to endpoints, parameters, or authentication methods), or if you make changes to the connected services (like updating fields in a Google Sheet), review and test your Zaps to ensure they continue to work as expected. It's also a good practice to periodically test your Zaps to ensure they're functioning correctly, especially if they run infrequently. ### 3. Leverage Zapier's Built-in Apps for Enhanced Functionality - **Data Parsing and Formatting**: Utilize Zapier's Formatter app to transform data formats, parse JSON responses effectively, or customize date and text outputs from the jobdata API. This is crucial for ensuring the data fits the expected input format of subsequent steps or external systems you're integrating with, like CRM platforms, databases, or notification services. ## Conclusion By following these steps, you've successfully set up a Zapier workflow that integrates with the jobdata API, automating the process of fetching and utilizing job listing data. This Zap can significantly enhance your ability to analyze job market trends, update job boards, or enrich your HR processes, all within Zapier's easy-to-use platform. Whether you're a business analyst, recruiter, or job seeker, this integration opens up a world of possibilities for streamlining your workflows and making data-driven decisions. # How to Determine if a Job Post Requires Security Clearance Filter job posts requiring security clearance using the jobdata API by examining keywords in the title and description_string fields. Source: https://jobdataapi.com/c/how-to-determine-if-a-job-post-requires-security-clearance/index.md --- When searching for job listings, especially within government, defense, or cybersecurity sectors, it's important to identify whether a position requires security clearance. Security clearance is a designation that allows individuals to access classified information, and it's often a prerequisite for roles involving sensitive or confidential duties. This guide will show you how to filter job posts that require security clearance using the Jobdata API by examining specific keywords in the job `title` and `description_string` fields. ## Key Terms to Identify Security Clearance Requirements Job posts requiring security clearance typically include specific keywords within the job title or description. The following keywords are commonly used: - **clearance: secret** - **clearance: top secret** - **dod secret** - **poly level clearance** - **public trust clearance** - **secret clearance** - **security clearance** - **security vetting clearance** - **ts/sci** (Top Secret/Sensitive Compartmented Information) These terms might appear in different formats or variations, so considering multiple keyword combinations is essential. ## Filtering Job Listings for Security Clearance To identify jobs requiring security clearance, you'll need to first retrieve job listings from the Jobdata API and then filter them locally using the `title` and `description_string` fields. The `description_str=true` switch should be used when querying the API to ensure that the response includes an already cleaned, stripped, and lowercased version of the job description (`description_string`), making keyword searches easier. ### Example Request in Python Here's how you can make an initial API request to retrieve job listings, ensuring that the response includes the `description_string`: ```python import requests url = "https://jobdataapi.com/api/jobs/" params = { "description_str": "true", } headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, params=params, headers=headers) job_listings = response.json().get('results', []) ``` ### Filtering the Job Listings Once you have the job listings, you can filter them locally by searching for security clearance keywords within the `title` and `description_string` fields: ```python clearance_keywords = [ "clearance: secret", "clearance: top secret", "dod secret", "poly level clearance", "public trust clearance", "secret clearance", "security clearance", "security vetting clearance", "ts/sci" ] filtered_jobs = [] for job in job_listings: title = job.get("title", "").lower() description = job.get("description_string", "") if any(keyword in title for keyword in clearance_keywords) or \ any(keyword in description for keyword in clearance_keywords): filtered_jobs.append(job) # Print the filtered jobs that require security clearance for job in filtered_jobs: print(f"Title: {job['title']}, Location: {job['location']}") ``` ### Understanding the Keywords - **Security Clearance Levels:** Terms like `secret`, `top secret`, and `ts/sci` indicate different levels of security clearance, typically mentioned prominently in the job title or description. - **Public Trust Clearance:** This term often refers to roles that, while not requiring full security clearance, still involve handling sensitive information and require specific vetting. - **Polygraph:** Keywords like `poly level clearance` suggest the need for additional scrutiny, such as a lie detector test, beyond standard security clearance. - **DOD Secret:** This refers to security clearances managed by the Department of Defense, typically required for defense-related roles. ## Expanding Your Search Criteria While the keywords listed above are the most common, it's worth considering additional phrases that might indicate the need for security clearance: - **High-Risk Positions:** Jobs with terms like "background check required" or "security vetting" might not explicitly mention clearance but still involve significant security requirements. - **Government and Contractor Jobs:** Positions related to government or contractor work often require clearance, even if not explicitly stated in the job description. ## Conclusion Identifying job posts that require security clearance involves carefully filtering through job titles and descriptions for specific keywords. By using the `description_str=true` parameter in your Jobdata API request, you can obtain a cleaner job description for easier keyword searching. This approach ensures that your job search is targeted and efficient, particularly if you're seeking or already possess the necessary security clearances for these roles. # Converting Annual FTE Salary to Monthly, Weekly, Daily, and Hourly Rates This tutorial will guide you through the process of translating the annual FTE salary back into its original units (monthly, weekly, daily, or hourly) using the logic implemented in the backend. Source: https://jobdataapi.com/c/converting-annual-fte-salary-to-monthly-weekly-daily-and-hourly-rates/index.md --- ## Understanding FTE Salary Calculation The API returns salary data as an annual FTE salary, which standardizes compensation to reflect a full-time work year. However, in many cases, this annual salary may have been derived from smaller units such as hourly, daily, weekly, or monthly wages. To reverse this calculation, you can use the following formulas: - **Monthly Salary:** `Annual Salary ÷ 12` - **Weekly Salary:** `Annual Salary ÷ 50` - **Daily Salary:** `Annual Salary ÷ 250` - **Hourly Salary:** `Annual Salary ÷ 2000` These conversion factors are based on the following assumptions: - A standard work month has 4 weeks. - A standard work year has 50 weeks (accounting for 2 weeks of unpaid leave). - A standard work week has 5 workdays. - A standard workday has 8 working hours. ## Example Conversion Code Here is a Python snippet that demonstrates how to convert the annual FTE salary back into monthly, weekly, daily, or hourly rates: ```python def convert_annual_to_original_units(annual_salary, original_unit): if original_unit == 'month': monthly_salary = annual_salary / 12 return monthly_salary elif original_unit == 'week': weekly_salary = annual_salary / 50 return weekly_salary elif original_unit == 'day': daily_salary = annual_salary / 250 return daily_salary elif original_unit == 'hour': hourly_salary = annual_salary / 2000 return hourly_salary else: raise ValueError("Invalid original unit provided. Choose from 'month', 'week', 'day', or 'hour'.") # Example usage: annual_salary = 120000 # Example FTE salary print("Monthly Salary:", convert_annual_to_original_units(annual_salary, 'month')) print("Weekly Salary:", convert_annual_to_original_units(annual_salary, 'week')) print("Daily Salary:", convert_annual_to_original_units(annual_salary, 'day')) print("Hourly Salary:", convert_annual_to_original_units(annual_salary, 'hour')) ``` ### Output Assuming an annual salary of $120,000: - **Monthly Salary:** $10,000 - **Weekly Salary:** $2,400 - **Daily Salary:** $480 - **Hourly Salary:** $60 ## Conversion Details ### Monthly Salary To get the original monthly salary from the annual FTE salary: ```python monthly_salary = annual_salary / 12 ``` ### Weekly Salary To get the original weekly salary from the annual FTE salary: ```python weekly_salary = annual_salary / 50 ``` ### Daily Salary To get the original daily salary from the annual FTE salary: ```python daily_salary = annual_salary / 250 ``` ### Hourly Salary To get the original hourly salary from the annual FTE salary: ```python hourly_salary = annual_salary / 2000 ``` ## Important Considerations ### 1. Salary Numbers as Guidelines While the API provides salary information, it's important to remember that these figures aren't always precise. Salaries often involve negotiations, experience levels, and other factors that influence the final compensation. Therefore, the salary numbers should be viewed more as guidelines or ranges rather than exact figures. ### 2. Simplicity in Salary Data The API standardizes salary data into annual FTE base values to keep things simple. This approach simplifies filtering and comparing job salaries across different positions and locations, making it easier to understand overall compensation trends. ## Conclusion By following the above guidelines and using the provided Python code, developers can easily reverse-engineer the salary data provided by the Jobdata API to match the original payment intervals or base rates. Use this tutorial as a reference whenever you need to translate annual salary data into smaller units for detailed analysis or display in your applications. # Retrieving and Working with Industry Data for Imported Jobs A step-by-step guide through the process of retrieving industry information from the companies associated with the jobs you've already imported. Source: https://jobdataapi.com/c/retrieving-and-working-with-industry-data-for-imported-jobs/index.md --- ## Prerequisites Before diving into the tutorial, ensure you have the following: - **API Access**: You must have a valid API key for the jobdata API. If you don’t have one, [please subscribe](/accounts/pricing/) to get access. - **Imported Job Data**: You should have already imported job data locally using the `/api/jobs` endpoint. - **Basic Knowledge of REST APIs**: Understanding how to interact with RESTful APIs using tools like `curl` or programming languages such as Python. - **Python Installed**: We’ll use Python for the API calls in this tutorial. Ensure you have Python 3.x installed on your machine. ## Understanding the Job Data Schema When you import job data using the `/api/jobs` endpoint, each job entry contains a `company` object. This object includes basic information about the company that posted the job, such as the company ID, name, and logo. However, it does not directly include industry information. ### Example Job Data Response ```json { "id": 123, "title": "Software Engineer", "company": { "id": 45, "name": "Tech Innovators Ltd", "logo": "https://example.com/logo.png", "website_url": "https://techinnovators.com", "linkedin_url": "https://linkedin.com/company/tech-innovators", "twitter_handle": "@techinnovators" }, "location": "San Francisco, CA", "published": "2023-08-01T12:00:00Z", "description": "Job description here...", "experience_level": "MI", "salary_min": "80000", "salary_max": "120000", "salary_currency": "USD", "application_url": "https://techinnovators.com/careers/12345" } ``` In the above response, the `company` object only includes the company ID (`id`), but not the industry information. We need to retrieve the industry data separately. ## Step 1: Fetching Job Data If you haven’t already imported job data, you can use the `/api/jobs` endpoint to fetch it. Here’s how you can do it using Python. ### Example API Call to Fetch Jobs ```python import requests url = "https://jobdataapi.com/api/jobs" headers = { "Authorization": "Api-Key YOUR_API_KEY" } params = { "page": 1, "page_size": 500 } response = requests.get(url, headers=headers, params=params) if response.status_code == 200: jobs = response.json()["results"] print("Fetched jobs:", jobs) else: print("Failed to fetch jobs:", response.status_code, response.text) ``` This code fetches a list of jobs with the associated company data. You can adjust the `page_size` parameter to retrieve more jobs at once. The response will include the company ID, which is essential for the next steps. ## Step 2: Extracting Company IDs Once you have the job data locally, extract the company IDs. These IDs are required to query the company information from the jobdata API. ### Example: Extracting Company IDs ```python company_ids = [job["company"]["id"] for job in jobs] print("Extracted Company IDs:", company_ids) ``` This code snippet extracts the `id` field from the `company` object in each job entry and stores it in a list called `company_ids`. ## Step 3: Retrieving Company Information With the company IDs in hand, you can now query the `/api/companies` endpoint to retrieve detailed information about each company, including the industry they operate in. ### Example API Call to Fetch Company Information ```python company_info_url = "https://jobdataapi.com/api/companies" company_info_list = [] for company_id in company_ids: response = requests.get(f"{company_info_url}/{company_id}", headers=headers) if response.status_code == 200: company_info = response.json() company_info_list.append(company_info) print(f"Retrieved data for company ID {company_id}: {company_info['name']}") else: print(f"Failed to retrieve company info for ID {company_id}: {response.status_code}") # Example output: # Retrieved data for company ID 45: Tech Innovators Ltd ``` This code iterates through the list of company IDs and fetches the detailed information for each company. The industry information is included in the response under the `info_industry` key. ### Example Company Data Response ```json { "id": 45, "name": "Tech Innovators Ltd", "logo": "https://example.com/logo.png", "website_url": "https://techinnovators.com", "linkedin_url": "https://linkedin.com/company/tech-innovators", "twitter_handle": "@techinnovators", "github_url": "https://github.com/techinnovators", "info_description": "A leading tech company specializing in AI solutions.", "info_hq": "San Francisco, CA", "info_size": 200, "info_founded": 2010, "info_specialties": "AI, Machine Learning, Robotics", "info_industry": { "id": 3, "name": "Information Technology" }, "info_type": { "id": 2, "name": "Private" } } ``` In this response, the `info_industry` object contains both the `id` and `name` of the industry. ## Step 4: Extracting Industry Data Now that you have the detailed company information, you can extract the industry data for each company. ### Example: Extracting Industry Data ```python industry_data = [ { "company_id": company["id"], "company_name": company["name"], "industry_id": company["info_industry"]["id"], "industry_name": company["info_industry"]["name"] } for company in company_info_list ] print("Extracted Industry Data:", industry_data) ``` This code snippet creates a list of dictionaries, each containing the company ID, company name, industry ID, and industry name. This data can be used for further processing or storage. ## Step 5: Storing and Utilizing Industry Data Once you have extracted the industry data, you may want to store it in your local database or use it directly in your application. Here’s how you can approach this. ### Example: Storing Industry Data in a Database Assuming you’re using SQLite for local storage, here’s an example of how to store the industry data. ```python import sqlite3 # Connect to SQLite database (or create it) conn = sqlite3.connect("jobs.db") cursor = conn.cursor() # Create a table for storing industry data cursor.execute(""" CREATE TABLE IF NOT EXISTS industries ( company_id INTEGER PRIMARY KEY, company_name TEXT, industry_id INTEGER, industry_name TEXT ) """) conn.commit() # Insert the extracted industry data into the table cursor.executemany(""" INSERT INTO industries (company_id, company_name, industry_id, industry_name) VALUES (:company_id, :company_name, :industry_id, :industry_name) """, industry_data) conn.commit() print("Industry data stored successfully.") ``` ### Example: Querying Industry Data After storing the industry data, you can query it to enhance your job listings, generate reports, or perform further analysis. ```python # Example query: Get all companies in the 'Information Technology' industry cursor.execute(""" SELECT * FROM industries WHERE industry_name = 'Information Technology' """) it_companies = cursor.fetchall() print("Companies in the Information Technology industry:", it_companies) ``` This query retrieves all companies that operate in the "Information Technology" industry from the `industries` table. ## Conclusion By following this tutorial, you’ve learned how to: 1. Fetch job data using the jobdata API. 2. Extract company IDs from imported job data. 3. Retrieve detailed company information, including industry data. 4. Extract and store industry information locally. 5. Utilize the stored industry data for further analysis or integration into your application. Enriching your job listings with industry information adds significant value to your application, enabling better categorization, filtering, and insights. This tutorial should serve as a foundation for further enhancements and customizations based on your specific use case. # Optimizing API Requests: A Guide to Efficient jobdata API Usage A guide on how to make efficient requests using sessions and handle large data sets with pagination. Source: https://jobdataapi.com/c/optimizing-api-requests-a-guide-to-efficient-jobdata-api-usage/index.md --- ## Introduction The **jobdata API** provides access to a vast database of job listings, directly sourced from company ATS (Applicant Tracking Systems) and career platforms. Developers can leverage this API to integrate job data into their applications, from job boards to recruitment platforms. However, frequent requests to the API, especially when dealing with large datasets, can lead to overheads like increased latency, redundant authentication, and potential rate-limiting. This tutorial will guide you on how to make efficient requests using sessions and handle large data sets using pagination. We'll focus on the `/api/jobs` endpoint as an example to illustrate the best practices. ## Prerequisites Before we dive into the specifics, ensure that you have: - An [active API key](/accounts/pricing/) for authentication. - Basic understanding of REST APIs. - Familiarity with HTTP methods like GET, POST, etc. - Basic [Python knowledge](https://www.python.org/) if you wish to follow along with the Python examples. ## Authentication All requests to the jobdata API require authentication using an API key. This API key should be included in the header of each request. Here’s a standard header: ```sh Authorization: Api-Key YOUR_API_KEY ``` ## Why Use Sessions? ### Reducing Overhead When making multiple requests, each HTTP request creates a new connection, which involves overheads such as DNS resolution, TCP handshakes, and SSL/TLS negotiations. By using sessions, you maintain a persistent connection to the server, reducing this overhead. ### Managing Authentication Efficiently With sessions, you can set the authorization header once, and it will automatically be used for all subsequent requests made through that session. This is especially useful when making multiple API calls in a single script. ### Handling Cookies and Headers Some APIs may require maintaining certain cookies or headers between requests. Sessions automatically handle these, ensuring consistency across requests. ## Setting Up a Session in Python Python’s `requests` library makes it straightforward to work with sessions. Below is an example of how to set up a session for making efficient requests to the jobdata API. ```python import requests # Set up the session session = requests.Session() # Define the base URL base_url = 'https://jobdataapi.com/api' # Add the API key to the session headers session.headers.update({ 'Authorization': 'Api-Key YOUR_API_KEY', 'Content-Type': 'application/json' }) # Now all requests made using this session will include the API key ``` ## Pagination with `/api/jobs` The `/api/jobs` endpoint provides [access to job listings](/c/jobs-api-endpoint-documentation/). When working with large datasets, retrieving all jobs in a single request isn’t feasible due to the sheer volume and potential API limitations. Pagination helps you fetch data in smaller, manageable chunks. ### Query Parameters for Pagination The `/api/jobs` endpoint supports [pagination](/c/jobs-api-endpoint-documentation/#parameters) through two key query parameters: - **page**: Indicates the page number of the results. By default, it starts at `1`. - **page_size**: Determines the number of results returned per page. ### Example API Call with Pagination Let’s assume we want to fetch jobs in batches of 500. ```python # Define the endpoint with pagination parameters endpoint = f'{base_url}/jobs?page=1&page_size=500' # Make the GET request response = session.get(endpoint) # Check if the request was successful if response.status_code == 200: jobs = response.json() print(f"Fetched {len(jobs['results'])} jobs") else: print("Failed to fetch jobs:", response.status_code) ``` ### Looping Through Pages Fetching data page by page requires looping through until there are no more pages left. The API response includes `next` and `previous` URLs for navigation. Here’s how to loop through all pages: ```python def fetch_all_jobs(session, base_url): jobs = [] next_page_url = f'{base_url}/jobs?page=1&page_size=500' while next_page_url: response = session.get(next_page_url) data = response.json() # Extend the jobs list with the new results jobs.extend(data['results']) # Update the next_page_url next_page_url = data['next'] print(f"Fetched {len(data['results'])} jobs") return jobs # Fetch all jobs all_jobs = fetch_all_jobs(session, base_url) print(f"Total jobs fetched: {len(all_jobs)}") ``` ### Example Response Here's a snippet of the response you might receive when fetching jobs with pagination: ```json { "count": 75000, "next": "https://jobdataapi.com/api/jobs?page=2&page_size=500", "previous": null, "results": [ { "id": 123, "ext_id": "456abc", "company": { "id": 1, "name": "Company ABC", "logo": "https://companyabc.com/logo.png", "website_url": "https://companyabc.com", "linkedin_url": "https://linkedin.com/companyabc", "twitter_handle": "@companyabc", "github_url": "https://github.com/companyabc" }, "title": "Software Engineer", "location": "San Francisco, CA", "types": [{"id": 1, "name": "Full-time"}], "cities": [ { "geonameid": 5391959, "asciiname": "San Francisco", "name": "San Francisco", "country": { "code": "US", "name": "United States", "region": { "id": 1, "name": "California" } }, "timezone": "America/Los_Angeles", "latitude": "37.7749", "longitude": "-122.4194" } ], "has_remote": true, "published": "2024-08-24T12:00:00Z", "description": "This is a software engineer position...", "experience_level": "MI", "application_url": "https://companyabc.com/careers/apply/123", "salary_min": "70000", "salary_max": "90000", "salary_currency": "USD" } // ... more job listings ] } ``` ### Important Attributes in the Response - **count**: Total number of job listings available. - **next**: URL for the next page of results. - **previous**: URL for the previous page of results. - **results**: An array of job listings, each containing details like `id`, `title`, `location`, `company` information, etc. ## Handling Large Datasets When dealing with thousands of job listings, it's essential to handle them efficiently: ### Batch Processing Instead of loading all data at once, consider processing each page as it’s fetched. This reduces memory usage and allows for incremental processing. ```python def process_jobs(data): for job in data['results']: # Process each job print(f"Processing job: {job['title']} at {job['company']['name']}") def fetch_and_process_jobs(session, base_url): next_page_url = f'{base_url}/jobs?page=1&page_size=500' while next_page_url: response = session.get(next_page_url) data = response.json() # Process the jobs in the current page process_jobs(data) # Update the next_page_url next_page_url = data['next'] # Fetch and process jobs fetch_and_process_jobs(session, base_url) ``` ### Throttling Requests Even with a session, making too many requests in a short time frame might hit [API rate limits](/docs/#rate_limits). To prevent this, introduce a short delay between requests. ```python import time def fetch_jobs_with_delay(session, base_url, delay=1): next_page_url = f'{base_url}/jobs?page=1&page_size=500' while next_page_url: response = session.get(next_page_url) data = response.json() # Process the jobs in the current page process_jobs(data) # Update the next_page_url next_page_url = data['next'] # Introduce delay time.sleep(delay) # Fetch and process jobs with a delay between requests fetch_jobs_with_delay(session, base_url, delay=2) ``` ### Error Handling and Retry Logic Network errors, server timeouts, or other issues might interrupt the data fetching process. Implementing a retry logic ensures robustness. ```python def fetch_with_retries(session, url, retries=3): for attempt in range(retries): try: response = session.get(url) response.raise_for_status() # Raise HTTPError for bad responses return response.json() except requests.exceptions.RequestException as e: print(f"Attempt {attempt + 1} failed: {e}") if attempt + 1 == retries: raise time.sleep(2) # Wait before retrying def fetch_and_process_jobs_with_retries(session, base_url): next_page_url = f'{base_url}/jobs?page=1&page_size=500' while next_page_url: data = fetch_with_retries(session, next_page_url) # Process the jobs in the current page process_jobs(data) # Update the next_page_url next_page_url = data['next'] # Fetch and process jobs with retries fetch_and_process_jobs_with_retries(session, base_url) ``` ## Conclusion Efficient use of the jobdata API not only improves performance but also enhances the user experience in your applications. By utilizing sessions, you can reduce the overhead associated with repeated connections, and by properly managing pagination, you can handle large datasets without overwhelming your application or the API. Remember to always handle errors gracefully, use batch processing to keep memory usage in check, and respect API rate limits by introducing delays between requests. In summary: 1. **Use Sessions**: Maintain a persistent connection and reduce overhead. 2. **Paginate**: Fetch large datasets in manageable chunks. 3. **Batch Process**: Handle data incrementally to reduce memory usage. 4. **Throttle Requests**: Avoid hitting rate limits by spacing out requests. 5. **Retry Logic**: Implement robust error handling to manage network issues. With these techniques, you can make the most of the jobdata API in a scalable and efficient manner. # Merging Job Listings from Multiple Company Entries Efficiently retrieve job listings associated with specific companies. Source: https://jobdataapi.com/c/merging-job-listings-from-multiple-company-entries/index.md --- In this tutorial, we will explore how to effectively merge job listings from a company that may appear multiple times in the Jobdata API due to different divisions, regional entities, or separate Applicant Tracking Systems (ATS). This is a common scenario for large organizations, such as universities or multinational corporations, where each division may have its own job postings but share the same overarching company identity. ## Understanding the Problem When querying the Jobdata API, you may encounter multiple entries for the same company. For example, Johns Hopkins University may have separate ATS accounts for faculty/teaching positions and administrative jobs. Each of these accounts will return job listings under the same company name but may have different job types and locations. ### Key Points to Consider: - **Company Name**: Usually consistent across different entries. - **Website and Social Accounts**: Often the same, making it easier to match entries. - **No Duplicate Job Listings**: Different ATS systems typically do not duplicate job listings, as they cater to different job types. ## Steps to Merge Job Listings 1. **Fetch Company Data**: Use the `/api/companies/` endpoint to retrieve all company entries. 2. **Identify Unique Companies**: Use the company name, website, or social media links to identify unique companies. 3. **Fetch Job Listings**: For each unique company, fetch job listings using the `/api/jobs/` endpoint. 4. **Merge Listings**: Combine job listings from different entries into a single list for each unique company. ### Example: Merging Job Listings for Johns Hopkins University #### Step 1: Fetch Company Data You can search for companies by name or domain name using the following queries: **Search by Company Name:** ```python import requests url = "https://jobdataapi.com/api/companies/" params = { "name": "Johns Hopkins University" } headers = { "Authorization": "Api-Key YOUR_API_KEY" } response = requests.get(url, headers=headers, params=params) companies_data = response.json() print(companies_data) ``` **Search by Domain Name:** ```python url = "https://jobdataapi.com/api/companies/" params = { "website": "jhu.edu" } response = requests.get(url, headers=headers, params=params) companies_data = response.json() print(companies_data) ``` #### Step 2: Identify Unique Companies After fetching the company data, you can loop through the results to identify unique companies based on their name or website. ```python unique_companies = {} for company in companies_data['results']: company_id = company['id'] # Use company ID as the unique identifier unique_companies[company_id] = company # Store the company using its ID ``` #### Step 3: Fetch Job Listings Now that you have a list of unique companies, you can fetch job listings for each one. ```python all_jobs = [] for company in unique_companies.values(): company_id = company['id'] jobs_url = f"https://jobdataapi.com/api/jobs/?company_id={company_id}" response = requests.get(jobs_url, headers=headers) jobs_data = response.json() # Append jobs to the all_jobs list all_jobs.extend(jobs_data['results']) ``` #### Step 4: Merge Listings Since the job listings are already unique (as per the API's design), you can simply return or process the `all_jobs` list. ```python # Print all unique job listings for job in all_jobs: print(f"Title: {job['title']}, Location: {job['location']}, Company: {job['company']['name']} (ID: {job['company']['id']})") ``` ### Complete Example Code Here’s the complete code that combines all the steps: ```python import requests # Set your API key API_KEY = "YOUR_API_KEY" headers = { "Authorization": f"Api-Key {API_KEY}" } # Step 1: Fetch Company Data def fetch_companies_by_name(name): url = "https://jobdataapi.com/api/companies/" params = {"name": name} response = requests.get(url, headers=headers, params=params) return response.json() # Step 2: Identify Unique Companies def identify_unique_companies(companies_data): unique_companies = {} for company in companies_data['results']: company_id = company['id'] # Use company ID as the unique identifier unique_companies[company_id] = company # Store the company using its ID return unique_companies # Step 3: Fetch Job Listings def fetch_jobs_for_companies(unique_companies): all_jobs = [] for company in unique_companies.values(): company_id = company['id'] jobs_url = f"https://jobdataapi.com/api/jobs/?company_id={company_id}" response = requests.get(jobs_url, headers=headers) jobs_data = response.json() all_jobs.extend(jobs_data['results']) return all_jobs # Main Execution if __name__ == "__main__": company_name = "Johns Hopkins University" companies_data = fetch_companies_by_name(company_name) unique_companies = identify_unique_companies(companies_data) all_jobs = fetch_jobs_for_companies(unique_companies) # Print all unique job listings for job in all_jobs: print(f"Title: {job['title']}, Location: {job['location']}, Company: {job['company']['name']} (ID: {job['company']['id']})") ``` ## Searching for Job Listings by Company Name or Website (Domain) In the following example, we will demonstrate how to search for job listings directly using the `/api/jobs/` endpoint by filtering based on either the `company_name` or `company_website` parameters. This allows you to retrieve job listings that match a specific company name or website, leveraging the internal "like" search functionality of the database. #### Step 1: Search by Company Name You can search for job listings by specifying the `company_name` parameter in your request. This will return all job listings associated with companies that have names similar to the one you provide. **Python Code Example: Search by Company Name** ```python import requests # Set your API key API_KEY = "YOUR_API_KEY" headers = { "Authorization": f"Api-Key {API_KEY}" } # Function to search jobs by company name def search_jobs_by_company_name(company_name): url = "https://jobdataapi.com/api/jobs/" params = { "company_name": company_name # Using company_name parameter } response = requests.get(url, headers=headers, params=params) return response.json() # Example usage if __name__ == "__main__": company_name = "Johns Hopkins University" jobs_data = search_jobs_by_company_name(company_name) # Print job listings for job in jobs_data['results']: print(f"Title: {job['title']}, Location: {job['location']}, Company: {job['company']['name']}") ``` #### Step 2: Search by Company Website Similarly, you can search for job listings by specifying the `company_website` parameter. This will return job listings for companies that have websites matching the provided URL. **Python Code Example: Search by Company Website** ```python # Function to search jobs by company website def search_jobs_by_company_website(company_website): url = "https://jobdataapi.com/api/jobs/" params = { "company_website": company_website # Using company_website parameter } response = requests.get(url, headers=headers, params=params) return response.json() # Example usage if __name__ == "__main__": company_website = "jhu.edu" jobs_data = search_jobs_by_company_website(company_website) # Print job listings for job in jobs_data['results']: print(f"Title: {job['title']}, Location: {job['location']}, Company: {job['company']['name']}") ``` ### Complete Example Code Here’s the complete code that combines both search functionalities: ```python import requests # Set your API key API_KEY = "YOUR_API_KEY" headers = { "Authorization": f"Api-Key {API_KEY}" } # Function to search jobs by company name def search_jobs_by_company_name(company_name): url = "https://jobdataapi.com/api/jobs/" params = { "company_name": company_name # Using company_name parameter } response = requests.get(url, headers=headers, params=params) return response.json() # Function to search jobs by company website def search_jobs_by_company_website(company_website): url = "https://jobdataapi.com/api/jobs/" params = { "company_website": company_website # Using company_website parameter } response = requests.get(url, headers=headers, params=params) return response.json() # Main Execution if __name__ == "__main__": # Search by company name company_name = "Johns Hopkins University" jobs_data_name = search_jobs_by_company_name(company_name) print(f"Job listings for {company_name}:") for job in jobs_data_name['results']: print(f"Title: {job['title']}, Location: {job['location']}, Company: {job['company']['name']}") # Search by company website company_website = "jhu.edu" jobs_data_website = search_jobs_by_company_website(company_website) print(f"\nJob listings for website {company_website}:") for job in jobs_data_website['results']: print(f"Title: {job['title']}, Location: {job['location']}, Company: {job['company']['name']}") ``` This functionality allows you to efficiently retrieve job listings associated with specific companies, making it easier to aggregate and display relevant job opportunities for users. ## Conclusion By following the steps outlined in this tutorial, you can effectively merge job listings from multiple entries of the same company in the Jobdata API. The shown approaches ensure that you maintain a clean and organized dataset, allowing for better job search experiences and insights into hiring trends. # Fetching and Maintaining Fresh Job Listings Efficiently fetch and maintain fresh job listings using the jobdata API by retrieving recent jobs and checking for expired listings daily, ensuring a clean and relevant local job database. Source: https://jobdataapi.com/c/fetching-and-maintaining-fresh-job-listings/index.md --- In this tutorial, we will explore a strategy to fetch the latest job listings from the jobdata API while ensuring that we keep our data fresh and up-to-date. We will utilize the `/api/jobs/` endpoint (see [docs](/c/jobs-api-endpoint-documentation/)) to retrieve recent job listings and the `/api/jobsexpired/` endpoint (see [docs](/c/jobs-expired-api-endpoint-documentation/)) to check for expired jobs. This approach will help you maintain a clean and relevant job database. ## Background and Design Rationale The process described here is designed to ensure efficient and cost-effective job listing management by separating active job retrieval and expiration tracking into two endpoints. The `/api/jobs/` endpoint provides detailed, (non-expired with the `exclude_expird=true` flag) job data for initial imports, while the `/api/jobsexpired/` endpoint offers a lightweight feed of recently expired jobs, including their expiration dates. This two-step process optimizes resource usage by avoiding repeated fetching of full job details and focusing only on updating expiration statuses in your local database. By periodically checking the `/api/jobsexpired/` feed and matching it against your database, you can maintain a fresh and accurate dataset with minimal API calls. ## Prerequisites Before we begin, ensure you have the following: 1. **API Key**: You need a valid API key from jobdata API with an active **access pro** subscription. If you don't have one, you can generate it from your dashboard after [subscribing to the plan](/accounts/pricing/). 2. **Python Environment**: Make sure you have Python installed along with the `requests` library. You can install it using pip if you haven't already: ```bash pip install requests ``` ## Step 1: Fetch Recent Job Listings We will start by fetching job listings that are not expired and have been published within the last 30 days. We will use the `exclude_expired=true` and `max_age=30` parameters in our request to the [`/api/jobs/` endpoint](/c/jobs-api-endpoint-documentation/). ### Example Code to Fetch Jobs with Pagination ```python import requests from datetime import datetime, timedelta # Constants API_KEY = "YOUR_API_KEY" # Replace with your actual API key JOBS_URL = "https://jobdataapi.com/api/jobs/" EXPIRED_URL = "https://jobdataapi.com/api/jobsexpired/" FETCH_DATE = datetime.now() # Current date for fetching jobs # Function to fetch recent job listings with pagination def fetch_recent_jobs(): headers = {"Authorization": f"Api-Key {API_KEY}"} params = { "exclude_expired": "true", "max_age": 30, "page_size": 1000, # Fetch 1000 jobs per request "page": 1 # Start from the first page } all_jobs = [] # List to store all fetched jobs while True: response = requests.get(JOBS_URL, headers=headers, params=params) if response.status_code == 200: job_data = response.json() all_jobs.extend(job_data['results']) # Add fetched jobs to the list # ...or directly import jobs into your local DB here... print(f"Fetched {len(job_data['results'])} jobs from page {params['page']}.") # Check if there is a next page if job_data['next']: params['page'] += 1 # Increment page number for the next request else: break # Exit loop if no more pages else: print("Error fetching jobs:", response.status_code, response.text) break return all_jobs # Fetch jobs recent_jobs = fetch_recent_jobs() print(f"Total fetched job listings: {len(recent_jobs)}") ``` ### Explanation - We set the `exclude_expired` parameter to `true` to filter out expired jobs. - The `max_age` parameter is set to `30` to only fetch jobs published in the last 30 days. - We specify `page_size` as `1000` to minimize the number of requests. - The `while` loop handles pagination, fetching all available job listings sequentially. ## Step 2: Check for Expired Jobs Next, we will check for expired jobs daily. We will use the [`/api/jobsexpired/` endpoint](/c/jobs-expired-api-endpoint-documentation/) to retrieve jobs that have expired since the last fetch date minus one day. This buffer ensures we don't miss any jobs that may have expired just before our check. ### Example Code to Check Expired Jobs ```python # Function to check for expired jobs def check_expired_jobs(): headers = {"Authorization": f"Api-Key {API_KEY}"} expired_since = (FETCH_DATE - timedelta(days=1)).strftime('%Y-%m-%d') # One day buffer params = { "expired_since": expired_since, "page_size": 1000, # Fetch 1000 expired jobs per request "page": 1 # Start from the first page } expired_job_items = [] # List to store all expired job items while True: response = requests.get(EXPIRED_URL, headers=headers, params=params) if response.status_code == 200: expired_data = response.json() print(f"Fetched {len(expired_data['results'])} expired job items from page {params['page']}.") expired_job_items.extend(expired_data['results']) # Add expired jobs to the list # ...or directly update jobs by their ID in your local DB here... # Check if there is a next page if expired_data['next']: params['page'] = params.get('page', 1) + 1 # Increment page number else: break else: print("Error fetching expired jobs:", response.status_code, response.text) break return expired_job_items # Check for expired jobs expired_jobs = check_expired_jobs() ``` ### Explanation - We calculate the `expired_since` date by subtracting one day from the current fetch date. - We use a `while` loop to paginate through the results, fetching up to 1000 expired jobs at a time. - The `next` link in the response helps us determine if there are more pages to fetch. ## Step 3: Update Your Database After (or while) fetching the expired jobs, you should update your local database to remove or mark these jobs as expired. You can match the job IDs from the expired jobs response against your local database entries. ### Example Code to Update Database ```python # Example function to update the database (pseudo-code) def update_database(expired_jobs): for job in expired_jobs: # Pseudo-code for database update print(f"Updating database for expired job ID: {job['id']}") # db.update_job_status(job['id'], status='expired') # Call the update function with the expired job IDs update_database(expired_jobs) ``` ### Explanation - The `update_database` function is a placeholder for your actual database update logic. You would replace the print statement with your database update code that matches jobs by IDs existing in your database and sets their expired date accordingly. ## Conclusion By following this tutorial, you have learned how to fetch recent job listings from the jobdata API while ensuring that you keep your data fresh by checking for expired jobs daily. This approach allows you to maintain a clean and relevant job database, enhancing the user experience for job seekers. ### Important Notes - Ensure that you do not make parallel requests to the API; instead, make requests sequentially to avoid hitting rate limits. - Consider implementing error handling and logging for production-level applications to track issues and performance. - Regularly review and optimize your fetching and updating logic to ensure efficiency and accuracy. Feel free to modify the code snippets to fit your specific use case and database structure! # Using the jobdata API for Machine Learning with Cleaned Job Descriptions Use our pre-processed job descriptions for machine learning, focusing on job title classification and skills extraction. Source: https://jobdataapi.com/c/using-the-jobdata-api-for-machine-learning-with-cleaned-job-descriptions/index.md --- In this tutorial, we will explore how to utilize the jobdata API to create a machine learning data pipeline for two specific use cases: **Job Title Classification** and **Skills Extraction from Job Descriptions**. We will focus on using the `description_string` field, which provides a cleaned version of job descriptions, making it ideal for text processing tasks. Additionally, we will filter our data to include only English job postings using the `language` parameter. ## Prerequisites Before we begin, ensure you have the following: 1. **API Key**: You need a valid API key with an active [access subscription](/accounts/pricing/). 2. **Python Environment**: Set up a [Python](https://www.python.org/) environment with the following libraries installed: - `requests` for making API calls. - `pandas` for data manipulation. - `scikit-learn` for machine learning tasks. - `nltk` for natural language processing tasks. You can install the required libraries using pip: ```bash pip install requests pandas scikit-learn nltk ``` ## Step 1: Fetching Job Data We will start by fetching job data from the API. We will use the `/api/jobs/` endpoint to retrieve job listings, filtering for English job postings and including the `description_str` parameter to activate the `description_string` value for each job posting in the results. ### Fetching Job Listings Here’s how to fetch job listings using Python: ```python import requests import pandas as pd # Define your API key and endpoint API_KEY = 'YOUR_API_KEY' url = "https://jobdataapi.com/api/jobs/" # Set parameters for the API request params = { "language": "en", # Filter for English job postings "description_str": "true", # Include cleaned description "page_size": 5000 # Number of results per page } # Set headers for authorization headers = { "Authorization": f"Api-Key {API_KEY}" } # Fetch job listings response = requests.get(url, headers=headers, params=params) data = response.json() # Convert results to a DataFrame job_listings = pd.DataFrame(data['results']) print(job_listings.head()) ``` ### Data Structure The `job_listings` DataFrame will contain various fields, including: - `id`: Job ID - `title`: Job title - `description_string`: Cleaned job description - `company`: Company information - `location`: Job location ## Step 2: Dynamic Job Title Classification ### Use Case Overview In this use case, we will classify job titles into categories dynamically using unsupervised learning techniques, such as clustering. This approach allows us to categorize job titles without predefined lists. ### Data Preparation 1. **Feature Extraction**: We will use the `description_string` for feature extraction. We can use TF-IDF (Term Frequency-Inverse Document Frequency) to convert text data into numerical format. ```python from sklearn.feature_extraction.text import TfidfVectorizer # Initialize TF-IDF Vectorizer vectorizer = TfidfVectorizer(stop_words='english') # Fit and transform the job descriptions X = vectorizer.fit_transform(job_listings['description_string']) ``` 2. **Clustering Job Titles**: We will use K-Means clustering to group job titles into categories. ```python from sklearn.cluster import KMeans # Define the number of clusters (categories) num_clusters = 8 # You can adjust this number based on your data kmeans = KMeans(n_clusters=num_clusters, random_state=42) # Fit the model kmeans.fit(X) # Assign cluster labels to job titles job_listings['cluster'] = kmeans.labels_ ``` ### Analyzing Clusters You can analyze the clusters to see which job titles belong to which category. ```python # Display job titles and their assigned clusters for cluster in range(num_clusters): print(f"\nCluster {cluster}:") print(job_listings[job_listings['cluster'] == cluster]['title'].values) ``` ## Step 3: Skills Extraction from Job Descriptions ### Use Case Overview In this use case, we will extract skills mentioned in job descriptions. This can help job seekers understand the skills required for various positions. ### Data Preparation 1. **Define Skills List**: Create a list of skills you want to extract. ```python # Example skills list skills_list = [ "Python", "Java", "SQL", "Machine Learning", "Data Analysis", "Project Management", "JavaScript", "HTML", "CSS", "Marketing", "Communication", "Teaching" ] ``` 2. **Extract Skills**: We will create a function to extract skills from the `description_string`. ```python def extract_skills(description, skills): found_skills = [skill for skill in skills if skill.lower() in description.lower()] return found_skills # Apply the function to extract skills job_listings['extracted_skills'] = job_listings['description_string'].apply(lambda x: extract_skills(x, skills_list)) ``` ### Analyzing Extracted Skills You can analyze the extracted skills to see which skills are most frequently mentioned across job postings. ```python # Flatten the list of extracted skills and count occurrences all_skills = [skill for sublist in job_listings['extracted_skills'] for skill in sublist] skills_count = pd.Series(all_skills).value_counts() print(skills_count) ``` ## Conclusion In this tutorial, we demonstrated how to leverage the jobdata API to create a machine learning data pipeline for two use cases: Dynamic job title classification and skills extraction from job descriptions. By utilizing the `description_string` field, we were able to quickly extract relevant information for our models without the need for any cleaning or filtering of HTML tags and other unusable content that usually appears in raw job posts. ### Next Steps - **Experiment with clustering**: Adjust the number of clusters in K-Means to see how it affects the categorization of job titles. - **Expand the skills list**: Include more skills to improve the extraction process. - **Paginate through more job results**: To increase your dataset, [implement pagination](/c/optimizing-api-requests-a-guide-to-efficient-jobdata-api-usage/#pagination-with-apijobs) in your API requests to fetch additional job listings. This can be done by iterating through pages (e.g. by using the URL provided by the `next` attribute when more pages for a query result are available) until you reach the desired number of job postings. - **Deploy the model**: Consider deploying the trained model as a web service for real-time predictions. By following these steps, you can effectively utilize job data for various machine learning applications, enhancing the job search experience for users. # A Two-Step Approach to Precision Job Filtering This tutorial presents a two-step method for optimizing API queries within the Life Sciences and Biotechnology industries, to ensure highly relevant job listings are identified more efficiently and accurately. Source: https://jobdataapi.com/c/a-two-step-approach-to-precision-job-filtering/index.md --- Fetching the right jobs form the API in specialized industries like Life Sciences and Biotechnology can be challenging. To streamline this process, we can leverage a two-step approach by filtering for title keywords first and then verify with description filters locally. Here we don't even need to use any full-text search capabilities from the API. In this article, we'll walk through a Python script that fetches job listings based on title keywords and filters them further using highly relevant keywords from job descriptions. ## Overview of the Method Our approach involves two main steps: 1. **API Query with Title Keywords:** We fetch job listings that match a set of predefined title keywords. These keywords are combined using the `|OR|` operator to ensure we capture a broad range of relevant job titles (you can combine up to 50 different keywords). 2. **Local Filtering with Description Keywords:** Once we have the raw job listings, we filter them locally to ensure each job description contains at least two or more highly relevant keywords. This ensures that the jobs are not only relevant by title but also by their actual content. By combining these two steps, we can efficiently narrow down job listings to those that are most relevant to the Life Sciences and Biotechnology industries. ## The Python Script Below is the Python script that implements this method. We'll break it down into its key components and explain each part in detail. ### Step 1: Define Keyword Lists We start by defining two lists of keywords: 1. **Title Keywords:** These are substrings that are likely to appear in job titles within the Life Sciences and Biotechnology industries. ```python title_keywords = [ "Biotech", "Life Sciences", "Biopharma", "Pharmaceutical", "Genomics", "Proteomics", "Bioinformatics", "Molecular Biology", "Cell Biology", "Biochemistry", "Clinical Research", "Regulatory Affairs", "Quality Assurance", "Biomanufacturing", "Biostatistics", "Pharmacology", "Toxicology", "Biomedical Engineer", "Scientist", "Research Associate", "Lab Technician" ] ``` 2. **Description Keywords:** These are highly relevant keywords that typically appear in job descriptions for positions in these industries. ```python description_keywords = [ "PCR", "ELISA", "CRISPR", "NGS", "RNA", "DNA", "cell culture", "flow cytometry", "mass spectrometry", "HPLC", "LC-MS", "GMP", "GLP", "FDA", "ICH", "clinical trials", "drug development", "bioprocessing", "fermentation", "protein purification", "assay development", "statistical modeling", "bioanalytical", "pharmacokinetics", "pharmacodynamics", "toxicology studies", "regulatory submissions" ] ``` ### Step 2: Fetch Jobs Using the API We define a function `fetch_jobs_by_title` to fetch job listings from the API based on the title keywords. The keywords are combined using the `|OR|` operator to create a single query string. ```python import requests API_URL = "https://jobdataapi.com/api/jobs/" API_KEY = "your_api_key_here" # Replace with your actual API key def fetch_jobs_by_title(title_keywords): """ Fetches job listings from the API based on title keywords using the |OR| operator. :param title_keywords: List of keyword substrings for job title search :return: List of job listings (each listing is a dictionary with 'title' and 'description' keys) """ # Join up to 50 title keywords with |OR| for the API query title_query = "|OR|".join(title_keywords) # Make the API request params = { "title": title_query, "description_md": True, # get Markdown version of job description "description_off": True, # switch off HTML version "exclude_expired": True, # only open positions "max_age": 90, # only jobs published in the past 90 days "api_key": API_KEY } response = requests.get(API_URL, params=params) # Check if the request was successful if response.status_code == 200: res_json = response.json() print(f"Found {res_json['count']} jobs based on title keywords.") return res_json.get("results", []) else: print(f"Error fetching jobs: {response.status_code}") return [] ``` Note: If you're not on an **access pro** subscription you can remove the `exclude_expired` parameter from the list above to make it work without one. ### Step 3: Filter Jobs Locally Next, we define a function `filter_jobs` to filter the fetched job listings based on the description keywords. Each job description is checked to ensure it contains at least three or more of the highly relevant keywords. ```python def filter_jobs(job_listings, description_keywords, min_keywords=3): """ Filters job listings to ensure each job description contains at least a minimum number of highly relevant keywords. :param job_listings: List of job listings (each listing is a dictionary with 'title' and 'description' keys) :param description_keywords: List of highly relevant keywords to check in job descriptions :param min_keywords: Minimum number of description keywords required for a job to be considered relevant :return: Filtered list of job listings """ filtered_jobs = [] for job in job_listings: description = job["description_md"].lower() # Count how many description keywords are in the job description keyword_count = sum(keyword.lower() in description for keyword in description_keywords) # If the job description contains at least min_keywords, add it to the filtered list if keyword_count >= min_keywords: filtered_jobs.append(job) return filtered_jobs ``` ### Step 4: Putting It All Together Finally, we combine the two functions to fetch and filter job listings. Here's the complete script: ```python if __name__ == "__main__": # Step 1: Fetch jobs using the title keywords job_listings = fetch_jobs_by_title(title_keywords) print(f"Fetched {len(job_listings)} jobs based on title keywords.") # Step 2: Filter jobs based on description keywords filtered_jobs = filter_jobs(job_listings, description_keywords, min_keywords=2) print(f"Filtered down to {len(filtered_jobs)} highly relevant jobs.") # Print the filtered jobs (for demonstration purposes) for job in filtered_jobs: print(f"Title: {job['title']}") print(f"Description: {job['description_md'][:100]}...") # Print first 100 chars of Markdown description print(f"URL: {job['application_url']}") print("-" * 50) ``` ## Example Output When you run the script, you'll see output similar to the following: ``` Found 35572 jobs based on title keywords. Fetched 100 jobs based on title keywords. Filtered down to 59 highly relevant jobs. Title: Immunology/Inflammation Expert (Postdoctoral Fellow / Scientist) Description: **Position Summary:** We are seeking a highly motivated Immunology/Inflammation Expert to join our ... URL: https://f.zohorecruit.com/jobs/Careers/3... -------------------------------------------------- Title: Data Scientist Description: **Knowledge, Skills, Competencies and Responsibilities: - Technical Competency: -** * Play a key ro... URL: https://v.zohorecruit.com/jobs/Careers/5... -------------------------------------------------- ``` ## Conclusion This script is highly customizable - you can adjust the keyword lists, modify the filtering criteria, or integrate it with other tools to further enhance its functionality. The goal here is to demonstrate the quite simple yet effective concept to get a large number relevant listings very quickly. The fastest way to create initial keyword and description filter lists is to ask you favorite LLM to generate it for you. After that you may review the results and modify or enhance them based on your experience or industry knowledge. # Introduction to Using Vector Search and Embeddings through the jobdata API Unlocking semantic job search and candidate matching by combining pre-generated embeddings with scalable vector databases. Source: https://jobdataapi.com/c/introduction-to-using-vector-search-and-embeddings-through-the-jobdata-api/index.md --- The way job search platforms, HR systems, and market researchers find and categorize jobs is rapidly changing. Traditional keyword search methods are still useful, but they often fall short when it comes to understanding the meaning behind words. A search for “machine learning engineer,” for example, may miss valuable postings that use phrases like “AI specialist” or “data scientist.” This is where vector embeddings and semantic search capabilities offered by the jobdata API come into play. Instead of matching only keywords, these tools allow you to match **concepts**, making it possible to uncover relationships between job postings and queries that would otherwise remain hidden. This guide explains how our vector search and embeddings work, how to use them effectively, and how to avoid common pitfalls when building on top of the service. ## Understanding Vector Embeddings in jobdata API At the core of the API’s [semantic search capabilities are vector embeddings](/c/vector-embeddings-and-search-api-documentation/). An embedding is a numerical representation of text—such as a job title and description—that captures its semantic meaning. In the jobdata API, embeddings are generated using OpenAI’s `text-embedding-3-small` model, which produces vectors with 768 dimensions in our case. Every job post in our database is preprocessed and assigned such an embedding. Because these embeddings are already generated and stored, you do not need to manage that process yourself. Instead, you can request embeddings for job listings directly via the API (`embed_3sh=true`), or you can run semantic searches by providing either a text query or your own embedding. ## Two Ways to Perform Vector Search The API supports two main approaches to semantic matching: 1. **Text-based vector search (`vec_text`)** You provide a text string—for instance, “remote software engineer with AI experience.” The API transforms this string into an embedding in real time and compares it to the pre-generated embeddings of job postings. The response includes jobs that are semantically similar to your input text. 2. **Embedding-based vector search (`vec_embedding`)** You provide a 768-dimensional embedding array directly. This is particularly useful if you already have embeddings from another source—for example, a candidate’s resume represented as an embedding—and want to match it against available jobs. This method requires a POST request, since the embedding itself is sent in the request body. Both approaches return results ordered by cosine distance, a measure of similarity between vectors. Lower values indicate greater similarity. ## Example API Calls To illustrate, consider the following examples in Python: **Retrieve jobs with embeddings included:** ```python import requests url = "https://jobdataapi.com/api/jobs/" params = {"embed_3sh": True, "page_size": 5} headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers, params=params) print(response.json()) ``` This is useful if you want to download job data along with embeddings for local processing or clustering. **Perform a semantic search with a text query:** ```python import requests url = "https://jobdataapi.com/api/jobs/" params = {"vec_text": "remote software engineer with AI experience", "max_dist": 0.45} headers = {"Authorization": "Api-Key YOUR_API_KEY"} response = requests.get(url, headers=headers, params=params) print(response.json()) ``` **Match jobs against an existing embedding:** ```python import requests url = "https://jobdataapi.com/api/jobs/" headers = {"Authorization": "Api-Key YOUR_API_KEY"} embedding = [-0.0649, 0.0485, 0.0700, 0.0242, ...] # shortened for clarity params = {"max_dist": 0.45, "country": "US"} payload = {"vec_embedding": embedding} response = requests.post(url, headers=headers, params=params, json=payload) print(response.json()) ``` ## Combining Semantic Search with Filters One of the strengths of the jobdata API is that vector search does not exist in isolation. You can combine semantic queries with [any of the API’s filters](/c/jobs-api-endpoint-documentation/)—for example, location, salary, experience level, or job type. This makes it possible to construct highly precise queries such as: * *“Find jobs similar to a data scientist role in fintech (job profile provided as embedding), but only in the United States, with a salary of at least $100,000, and with remote work options available (narrowing down through additional query filters).”* This combination of broad semantic understanding and fine-grained filtering produces results that are both relevant and tailored to your needs. ## Practical Applications The use cases for vector embeddings extend beyond straightforward job search: * **Improved candidate-job matching**: HR platforms can represent candidate profiles as embeddings and then match them against job postings semantically. This makes it easier to surface opportunities that align with a candidate’s skills and experience, even if the wording differs. * **Market research and analysis**: Analysts can cluster job embeddings to identify trends. For example, they might discover a growing cluster of roles related to “quantum computing” or notice that demand for “sustainability officers” is spreading across industries. * **Personalized recommendations**: A job platform can build an embedding that represents a user’s search history or profile, and then recommend jobs that are semantically closest. This provides a much more sophisticated recommendation system than simple keyword alerts. * **Salary benchmarking**: Since embeddings can cluster jobs with similar responsibilities, you can use them to identify salary ranges across comparable roles, even when the job titles differ. ## Why the API Should Be Used as a Data Source only A critical point for new users to understand is that the jobdata API is not intended to serve as a live backend for high-frequency, concurrent queries. Although the service is reliable, it enforces practical limits: no more than two requests in parallel and a maximum of ten requests per second (or somewhat higher with a certain top-tier subscription). Sending frequent queries directly from the client side is likely to cause bottlenecks or rate-limit issues. Instead, the API is best used as a **data source**: * Fetch embeddings or search results in batches. * Store them in your own database or vector search system (such as FAISS, Pinecone, or PostgreSQL with pgvector). * Serve results to your end users from your own infrastructure, ensuring fast response times and reduced API overhead. For example, you might run a daily job that fetches all “software engineering” positions with embeddings enabled. These can be stored locally, indexed in your vector database, and served instantly to users searching your platform. Meanwhile, the jobdata API continues to provide fresh data, but you avoid overwhelming it with repeated live queries. ## When to Use Full-Text Search Versus Vector Search Vector search excels at capturing meaning, but it is not always the right tool. In situations where you need an exact keyword match—such as requiring a specific certification or technology—full-text search remains invaluable. For example, “CFA certification” or “Kubernetes administrator” are precise requirements that might not be captured well by embeddings. The most effective approach is often hybrid: use vector search to cast a wide net based on concepts, and then refine results with filters or keyword searches to ensure precision. --- ## Example: Building a Semantic Job Search Pipeline The jobdata API provides access to up-to-date job postings with rich metadata and semantic embeddings. However, as explained earlier, it is not designed to serve as a real-time backend for a high number of concurrent queries. The best practice is to use the API as a **data ingestion layer**: fetch jobs with embeddings, store them locally, and build your own semantic search layer on top. This pipeline demonstrates how to: 1. Pull job postings with embeddings from the jobdata API. 2. Store and index them in a local vector database (FAISS). 3. Perform efficient semantic searches on your own infrastructure. 4. Periodically refresh the local dataset with new jobs from the API. ### 1. Prerequisites * A jobdata API key (with an active API access pro+ subscription or higher, required for embeddings). * Python environment with the following packages: ```bash pip install requests faiss-cpu pandas ``` * Basic familiarity with Python and data structures. ### 2. Fetch Jobs with Embeddings We start by requesting job postings with embeddings included (`embed_3sh=true`). To keep the example simple, we’ll fetch only a few, but in practice you could paginate through thousands. ```python import requests import pandas as pd API_KEY = "YOUR_API_KEY" BASE_URL = "https://jobdataapi.com/api/jobs/" headers = {"Authorization": f"Api-Key {API_KEY}"} params = {"embed_3sh": True, "page_size": 50} # adjust page_size as needed response = requests.get(BASE_URL, headers=headers, params=params) data = response.json()["results"] # Convert to DataFrame for easy handling jobs_df = pd.DataFrame(data, columns=["id", "title", "description", "embedding_3sh"]) print(jobs_df.head()) ``` At this point, you have a structured dataset containing job IDs, titles, descriptions, and their embeddings. ### 3. Store Jobs in a Vector Index We will use [FAISS](https://github.com/facebookresearch/faiss), an efficient open-source library for similarity search. Each job’s embedding is inserted into an index, and we keep a mapping from index positions back to job metadata. ```python import numpy as np import faiss # Extract embeddings and convert to numpy array embeddings = np.vstack(jobs_df["embedding_3sh"].values).astype("float32") # Create FAISS index (cosine similarity implemented via inner product on normalized vectors) dimension = embeddings.shape[1] index = faiss.IndexFlatIP(dimension) # Normalize vectors for cosine similarity faiss.normalize_L2(embeddings) # Add to index index.add(embeddings) # Store mapping of FAISS indices to job metadata id_map = dict(enumerate(jobs_df.to_dict("records"))) print(f"Stored {index.ntotal} jobs in vector index.") ``` ### 4. Run Semantic Queries with External Embeddings Now we can run queries directly against the local FAISS index. A query embedding can come from three possible sources: 1. **Direct jobdata query (`vec_text`)** Provide a natural language query string to the jobdata API, which will generate an embedding on the fly and return matching jobs. This is the quickest way to test semantic search, but it requires an API request every time. 2. **Externally generated embeddings (OpenAI API)** Use [OpenAI’s embedding endpoint](https://platform.openai.com/docs/guides/embeddings) (`text-embedding-3-small`) to generate vectors for any query text, candidate profile, or resume. This is often better for production workflows because you can search against your **local store of job embeddings**, avoiding repeated calls to the jobdata API. 3. **Embeddings from already imported jobs (`embedding_3sh`)** You can reuse imported job post embeddings directly as your query vector to find other semantically similar jobs. This enables **“related jobs”** or **“more like this”** features without regenerating embeddings. The second option is often preferred when building scalable applications, since it avoids hitting the jobdata API for every query. Here’s how you might do it with OpenAI and FAISS: ```python import numpy as np import faiss from openai import OpenAI # Assume you have already: # - Populated FAISS with job embeddings (from jobdata API) # - Built an `id_map` linking FAISS indices back to job metadata client = OpenAI(api_key="YOUR_OPENAI_API_KEY") ### OPTION 1: vec_text via jobdata API (returns jobs directly) # Good for one-off searches, but not efficient as a query source for FAISS ### OPTION 2: External embedding (OpenAI) query_text = "remote data scientist in healthcare" embedding_response = client.embeddings.create( model="text-embedding-3-small", input=query_text, dimensions=768, encoding_format="float", ) query_embedding = np.array(embedding_response.data[0].embedding, dtype="float32") ### OPTION 3: Use an existing job’s embedding as the query # Suppose you already stored job embeddings locally job_embedding = id_map[42]["embedding_3sh"] # pick a job to use as the "query" query_embedding = np.array(job_embedding, dtype="float32") # Normalize for cosine similarity (required for FAISS inner product search) faiss.normalize_L2(query_embedding.reshape(1, -1)) # Search in FAISS index k = 5 # number of nearest jobs to return distances, indices = index.search(query_embedding.reshape(1, -1), k) # Display results for rank, (dist, idx) in enumerate(zip(distances[0], indices[0]), start=1): job = id_map[idx] print(f"{rank}. {job['title']} (cosine similarity: {dist:.3f})") ``` By supporting all three strategies, you can tailor your system depending on the use case: * **vec\_text** → Best for direct ad-hoc search via the API. * **OpenAI embeddings** → Best for user-driven queries and resumes, combined with your cached job embeddings. * **Imported job embeddings (`embedding_3sh`)** → Best for “more like this job” or clustering similar jobs. This layered approach makes it possible to build a highly flexible job discovery system without overloading the jobdata API. ### 5. Keeping the Data Fresh To maintain a relevant index, you can run a scheduled job (e.g. nightly or every couple hours) that: 1. Fetches new postings from jobdata API with `embed_3sh=true`. 2. Adds them to your FAISS index and local metadata store. 3. Optionally removes expired or outdated postings. This way, your semantic search layer always reflects the most current data, but end users interact only with your infrastructure, ensuring fast response times. ### 6. Advantages of This Approach * **Performance**: End users query your local index, avoiding API latency and rate limits. * **Scalability**: FAISS or similar tools can handle millions of vectors efficiently. * **Flexibility**: You can combine semantic similarity with additional business logic (e.g., filtering by salary, location, or employer). * **Efficiency**: API usage is minimized, since you fetch and enrich data in bulk rather than on-demand for every query. ### 7. Next Steps * Experiment with hybrid search: combine semantic similarity from FAISS with keyword filters or metadata constraints. * Explore alternative vector databases such as Pinecone, Weaviate, or PostgreSQL with `pgvector` if you need cloud-native scalability. * Extend the pipeline to support **candidate matching** (embedding resumes) or **market research** (clustering embeddings to reveal trends). ## Summary Instead of being limited to keyword matches, you can now work with representations of meaning and context. This enables systems that not only “find jobs with the same words,” but also “understand what the job is about” — a critical leap forward for both employers and job seekers. With embeddings, you can: * **Deliver relevance that feels human.** A candidate searching for “AI researcher” can also be shown roles labeled “machine learning scientist” or “deep learning engineer.” Semantic similarity bridges the gap between rigid job titles and the fluid way people actually describe work. * **Build stronger candidate-job matching.** By embedding both job postings and candidate resumes/profiles, you can measure alignment on a deeper level than simple keyword overlap — highlighting opportunities where skills and requirements are semantically related, even if phrased differently. * **Uncover market insights.** Embeddings allow clustering, trend analysis, and anomaly detection across large sets of postings. This makes it possible to track how job roles are evolving, identify emerging skills, or compare regional labor markets more precisely. * **Enable personalized recommendations.** By combining semantic similarity with user history and preferences, you can recommend jobs that fit not just what a candidate typed into the search bar, but what they truly mean — and what they’re most likely to engage with. To get the most from these capabilities, it’s best to treat the jobdata API as a **data enrichment and ingestion layer**, rather than a live backend for end-user queries. The optimal architecture is: 1. **Fetch enriched jobs (with embeddings) from the API.** 2. **Cache them in your own infrastructure** — e.g., FAISS, Pinecone, Weaviate, or pgvector. 3. **Serve queries locally**, generating new embeddings as needed (e.g., from OpenAI) to compare against your stored data. 4. **Apply filters and business logic** (location, salary, seniority) on top of semantic similarity to maximize result relevance. For the vast majority of scenarios, this approach provides the right balance of speed, scalability, and cost-efficiency.