Getting started overview

Integrating with the Adzuna API involves a series of steps designed to get you from account creation to a functional API call. The process begins with setting up a developer account, which provides access to the necessary authentication credentials. Once authenticated, you can make requests to Adzuna's various API endpoints, such as the Job Search API, to retrieve job listing data. Adzuna provides a free tier for initial development and testing, allowing up to 5,000 requests per month without charge. Paid plans are available for higher usage requirements, starting at $50 per month for 20,000 requests. The developer portal offers comprehensive documentation, including an API reference and code examples in multiple programming languages, to facilitate integration. Adzuna's core products include APIs for job search, salary data, and job trends.

The following table outlines the key steps to get started:

Step What to Do Where
1. Sign Up Create a free developer account Adzuna Developer Portal signup page
2. Get Credentials Locate your Application ID and Application Key Adzuna Developer Dashboard
3. Construct Request Build your first API call with your credentials and desired parameters Your preferred development environment
4. Execute & Test Send the request and verify the response Your preferred development environment

Create an account and get keys

To access the Adzuna API, you must first register for a developer account. This process is straightforward and provides you with the unique credentials required for authentication. Navigate to the Adzuna developer portal signup page and complete the registration form. You will typically be asked for basic information such as your name, email address, and a password.

Upon successful registration and login, you will be redirected to your Adzuna Developer Dashboard. On this dashboard, you will find your essential API credentials:

  • Application ID (app_id): A unique identifier for your application.
  • Application Key (app_key): A secret key used to authenticate your requests.

It is crucial to keep your app_key secure, as it grants access to your API usage. Treat it like a password and avoid exposing it in client-side code, public repositories, or unsecured environments. For server-side applications, consider storing it as an environment variable or in a secure configuration management system. The Google Cloud documentation on API key best practices provides further guidance on managing API keys securely.

Your first request

With your app_id and app_key in hand, you can now make your first call to the Adzuna API. The primary endpoint for searching job listings is the Job Search API. All requests to Adzuna's API are made over HTTPS and require your app_id and app_key as query parameters.

Let's construct a simple request to search for 'software engineer' jobs in 'London'.

Request Structure

The base URL for the Job Search API is https://api.adzuna.com/v1/api/jobs. You'll need to specify the country (e.g., gb for Great Britain) and the page number. Essential query parameters include:

  • app_id: Your Application ID.
  • app_key: Your Application Key.
  • what: The job title or keywords to search for.
  • where: The location to search within.
  • content-type: Set to application/json to ensure JSON response.

Example Request (using curl)

Replace YOUR_APP_ID and YOUR_APP_KEY with your actual credentials.

curl -X GET \
  'https://api.adzuna.com/v1/api/jobs/gb/search/1?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY&what=software%20engineer&where=london&content-type=application/json' \
  -H 'Accept: application/json'

Example Request (Python)

This Python example uses the requests library to make the same API call.

import requests
import json

APP_ID = "YOUR_APP_ID"
APP_KEY = "YOUR_APP_KEY"

base_url = "https://api.adzuna.com/v1/api/jobs/gb/search/1"

params = {
    "app_id": APP_ID,
    "app_key": APP_KEY,
    "what": "software engineer",
    "where": "london",
    "content-type": "application/json"
}

headers = {
    "Accept": "application/json"
}

response = requests.get(base_url, params=params, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")

Expected Response Structure

A successful response will return a JSON object containing job listings, metadata, and pagination information. The core job data will be within the results array. An example (truncated) structure:

{
  "count": 12345,
  "mean": 65000,
  "results": [
    {
      "id": "1234567890",
      "title": "Software Engineer",
      "company": {
        "display_name": "Tech Solutions Inc."
      },
      "location": {
        "display_name": "London"
      },
      "description": "Join our team...",
      "redirect_url": "https://www.adzuna.com/job/...
    }
  ]
}

For detailed information on response fields and additional query parameters, consult the Adzuna Job Search API documentation.

Common next steps

Once you have successfully made your first API call and received job data, you can explore more advanced features and integrations:

  1. Explore other API Endpoints: Adzuna offers additional APIs beyond job search, including the Job Salary API for salary benchmarking and the Job Trends API for market research on job trends.
  2. Implement Pagination: For queries that return a large number of results, implement pagination using the page parameter to retrieve all available data efficiently.
  3. Refine Search Queries: Utilize advanced search parameters such as max_days_old, salary_min, salary_max, and category to filter results more precisely.
  4. Error Handling: Implement robust error handling in your application to gracefully manage scenarios such as rate limits, invalid parameters, or server errors. The API returns standard HTTP status codes and error messages in JSON format.
  5. Monitor Usage: Keep track of your API usage on your Adzuna Developer Dashboard to stay within your free tier limits or monitor usage against your paid plan.
  6. Review Pricing: If your application requires more than 5,000 requests per month, review the Adzuna pricing page to choose a suitable paid plan.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for the Adzuna API:

  • Check API Keys: Double-check that your app_id and app_key are correct and exactly match those found on your Adzuna Developer Dashboard. Even a single character mismatch will lead to authentication failures.
  • Verify URL Encoding: Ensure all query parameters, especially those with spaces or special characters (e.g., "software engineer"), are correctly URL-encoded. Most HTTP client libraries handle this automatically, but manual construction requires attention.
  • Review Status Codes: Pay attention to the HTTP status code returned in the API response. Common codes include:
    • 200 OK: Success.
    • 400 Bad Request: Often due to missing or invalid parameters. Check your query string.
    • 401 Unauthorized: Incorrect or missing app_id or app_key.
    • 403 Forbidden: Your account may have exceeded its rate limit, or the key is inactive.
    • 404 Not Found: Incorrect endpoint path.
    • 5xx Server Error: An issue on Adzuna's side.
  • Consult Documentation: Refer to the specific API endpoint documentation for required parameters and valid values.
  • Check Rate Limits: If you receive a 403 Forbidden error, you might have hit your rate limit. The free tier has a limit of 5,000 requests per month.
  • Network Connectivity: Ensure your development environment has a stable internet connection and is not blocked by a firewall from accessing api.adzuna.com.
  • Use a Tool: Tools like Postman or Insomnia can help construct and test API requests independently of your code, isolating potential issues to your application logic.