Job Cities API Endpoint Documentation

Table of contents

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

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)

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

{
  "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"
    },
    {
      "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"
    },
    {
      "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"
    }
  ]
}

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.

Related Docs