Job States API Endpoint Documentation

Table of contents

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 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 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)

curl -X GET "https://jobdataapi.com/api/jobstates/?country_code=GB" \
     -H "Authorization: Api-Key YOUR_API_KEY"

Example Request (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

{
  "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.

Related Docs