# List distinct values of a field - Job Postings API

`GET /api/v2/meta/jobs/distinct` - Job Postings API

Use this endpoint to find valid filter values (e.g. which industries or workplaces exist) - not to get job postings. This endpoint returns a list of distinct field values for the given query parameter. The response is per default a simple JSON object containing a list of keys usable as query parameter values and the count of jobs with this field value. With the format parameter other output formats can be requested. Notes This endpoint is not included in every plan (see Errors & billing). Without it, the response is 403 with requiredPlan and pricingUrl. The results are capped at 500 values and are calculated from job postings within the last month (i.e., current date minus 1 month). Usage Examples Used workPlace values: 
 `/api/v2/meta/jobs/distinct?field=workPlace` Used industry values: 
 `/api/v2/meta/jobs/distinct?field=industry`

## Request

Base URL: `https://daily-international-job-postings.p.rapidapi.com` - authentication: see [How to authenticate](https://api.techmap.io/quickstart#how-to-authenticate).

### curl

```bash
curl --request GET \
  --url 'https://daily-international-job-postings.p.rapidapi.com/api/v2/meta/jobs/distinct?field=workPlace' \
  --header 'X-RapidAPI-Key: YOUR_API_KEY' \
  --header 'X-RapidAPI-Host: daily-international-job-postings.p.rapidapi.com'
```

### Python

```python
import requests

url = "https://daily-international-job-postings.p.rapidapi.com/api/v2/meta/jobs/distinct"
params = {"field": "workPlace"}
headers = {
    "X-RapidAPI-Key": "YOUR_API_KEY",
    "X-RapidAPI-Host": "daily-international-job-postings.p.rapidapi.com",
}

response = requests.get(url, params=params, headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
```

### JavaScript

```javascript
// Node.js 18+ or browser
const url = new URL('https://daily-international-job-postings.p.rapidapi.com/api/v2/meta/jobs/distinct');
url.search = new URLSearchParams({ 'field': 'workPlace' });

const response = await fetch(url, {
  headers: {
    'X-RapidAPI-Key': 'YOUR_API_KEY',
    'X-RapidAPI-Host': 'daily-international-job-postings.p.rapidapi.com',
  },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(await response.json());
```

### Java

```java
// Java 11+
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class TechmapExample {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://daily-international-job-postings.p.rapidapi.com/api/v2/meta/jobs/distinct?field=workPlace"))
            .header("X-RapidAPI-Key", "YOUR_API_KEY")
            .header("X-RapidAPI-Host", "daily-international-job-postings.p.rapidapi.com")
            .GET()
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() != 200) throw new RuntimeException(response.statusCode() + ": " + response.body());
        System.out.println(response.body());
    }
}
```

## Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `field` (required) | query | string | A field name used in a query as a parameter |
| `format` | query | string | The format of the output in json, csv, rss, atom, xml, or parquet (e.g., `format=rss`) Values: `json`, `csv`, `rss`, `atom`, `xml`, `parquet`. |

## Responses

| Status | Description |
|---|---|
| **200** | Success - indicating a correct query execution with results |
| **400** | Bad Request - A parameter value could not be parsed, e.g. an unknown `countryCode`, an invalid date or `sort` value. **Solution:** Check the value against the parameter description. The `message` names the invalid parameter. |
| **401** | Unauthorized - The key is missing or invalid, or the request was sent directly to the backend instead of RapidAPI. **Solution:** Send your key in the header `X-RapidAPI-Key` and use the base URL `https://daily-international-job-postings.p.rapidapi.com`. Copy the key again from the RapidAPI listing if it was rotated. |
| **403** | Forbidden - Either you are not subscribed to this API ("You are not subscribed to this API."), or the endpoint is not included in your plan (e.g. `/api/v2/meta/jobs/distinct` and `/api/v2/meta/jobs/statistics` need at least the Pro plan). **Solution:** Subscribe to the Basic plan, or upgrade to the plan named in `requiredPlan`. The response contains `message`, `requiredPlan` and `pricingUrl`. |
| **404** | Not Found - The endpoint path does not exist (typo, wrong API version) or a required search parameter is missing, or the requested `field` does not exist. **Solution:** Check the path and add at least one search parameter (e.g. `countryCode`). The `message` lists the allowed parameters or fields. |
| **405** | Method Not Allowed - Another HTTP method than GET was used. **Solution:** Use GET. |
| **429** | Too Many Requests - Too many requests in a short time window (rate limit of your RapidAPI plan, e.g. 1 request/second on Basic). This is **not** a monthly limit - the plans have no hard limit, extra requests are billed as overage. RapidAPI also answers 429 after repeated calls with an invalid key. **Solution:** Slow down and retry with exponential backoff (e.g. 1 s, 2 s, 4 s). If it persists, check that your key is valid. |
| **500** | Internal Server Error - An unexpected error on our side. **Solution:** Retry once. If it persists, contact data@techmap.io with the full request URL (without your key). |
| **503** | Service Unavailable - The search backend is temporarily unavailable. **Solution:** Retry later with exponential backoff. |
| **509** | Bandwidth Limit Exceeded - The response would be larger than 6 MB. **Solution:** Request a more compact `format` or narrow the query. |

## Example response

```json
{
  "api": "Techmap.io Job Posting API",
  "apiVersion": "v2.7.1",
  "apiEndpoint": "GET statistics on a searchable field from endpoint '/api/v2/jobs/' such as 'workPlace', 'workType', 'contractType', 'careerLevel', 'occupation', 'department', 'industry', 'language', 'locale', 'timezone', 'timezoneOffset', 'countryCode', 'postCode', 'city', 'state', 'skills', 'company'",
  "aggregation": {
    "size": "0"
  },
  "totalCount": "6937315",
  "docsWithValue": "6937315",
  "coverage": "100",
  "valueCount": "42",
  "values": [
    {
      "key": "automotive",
      "doc_count": "166060"
    }
  ]
}
```

Interactive reference with all schemas: [Job Postings API reference](https://api.techmap.io/jobs-api#tag/Metadata/operation/distinct).