Multi-value Parameters Documentation

Table of contents

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:

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:

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:

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:

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:

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:

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:

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.

Related Docs