Getting started overview

Integrating with the Careerjet API allows developers to access job listing data directly, enabling the creation of custom job boards, search applications, or research tools. The process for getting started involves obtaining an API key, understanding the API's request parameters, and then making authenticated calls to retrieve job information. Careerjet provides a RESTful interface, returning data in XML or JSON format, which can be parsed and displayed in a developer's application (Careerjet Partners API documentation).

Before making requests, developers need to review the API's terms of service, especially regarding commercial versus non-commercial use, as this dictates the required API plan (Careerjet API pricing details). The API supports various parameters for filtering job results by keywords, location, and other criteria, allowing for specific queries. Example code in several programming languages is available, which can simplify initial integration efforts (Careerjet API reference documentation).

Quick reference steps

The following table provides a summary of the initial steps required to integrate with the Careerjet API:

Step What to do Where
1. Review API Documentation Familiarize yourself with API capabilities, terms, and example code. Careerjet Partners API page
2. Create an Account Register for a Careerjet partner account to obtain an API key. Careerjet API signup
3. Obtain API Key Locate your unique API key in your partner account dashboard. Careerjet partner account dashboard
4. Construct First Request Formulate an HTTP GET request to a search endpoint with your API key. Using your preferred HTTP client or programming language
5. Parse Response Process the XML or JSON response to extract job data. Your application's backend or frontend
6. Handle Errors Implement logic to manage API error codes and messages. Your application's error handling routines

Create an account and get keys

To begin using the Careerjet API, developers must first register for a partner account. This registration process is typically initiated through the Careerjet Partners API page. During signup, users generally provide contact information and agree to the service terms, which differentiate between commercial and non-commercial use cases. Non-commercial use often qualifies for free API access, while commercial applications require a paid subscription (Careerjet API pricing information).

Upon successful registration, an API key is generated. This key is a unique identifier that authenticates your application's requests to the Careerjet API. It is crucial to keep this key confidential and secure, as it grants access to API resources and is tied to your account's usage limits and billing. The API key is usually accessible within your Careerjet partner dashboard or provided directly upon account activation (Careerjet API documentation). When making API calls, this key is included as a parameter in the request URL.

Your first request

After obtaining your API key, the next step is to make a test request to ensure your setup is correct and you can retrieve data. The Careerjet API primarily uses HTTP GET requests to its search endpoint. A basic job search request requires at least a keyword (keywords) and your API key (user_ip, though the documentation typically refers to an affiliate ID or API key for authentication, with user_ip specifically for rate limiting and geographic relevance). For example, to search for 'software developer' jobs, you might construct a URL similar to this (replace YOUR_API_KEY with your actual key and ensure user_ip is set to the user's IP address for accurate results or your server's IP for testing):

GET https://public.api.careerjet.net/search?keywords=software%20developer&location=london&sort=date&affid=YOUR_API_KEY&user_ip=192.0.2.1 HTTP/1.1
Host: public.api.careerjet.net

In this example, affid is the parameter for your API key, and user_ip should reflect the end-user's IP for personalized results and proper rate limiting. The location parameter specifies a geographic filter, and sort dictates the order of results. The API supports various parameters to refine searches, such as start_num for pagination, pagesize for the number of results per page, and contracttype for job type filters (Careerjet API reference guide). You can choose to receive responses in XML or JSON by setting the format parameter to xml or json, respectively.

Here's an example using Python's requests library for a JSON response:

import requests
import json

api_key = "YOUR_API_KEY"
user_ip = "192.0.2.1" # Replace with the actual user's IP or your server's IP for testing
keywords = "software developer"
location = "london"
format_type = "json"

url = f"https://public.api.careerjet.net/search?keywords={keywords}&location={location}&affid={api_key}&user_ip={user_ip}&format={format_type}"

try:
    response = requests.get(url)
    response.raise_for_status() # Raise an HTTPError for bad responses (4xx or 5xx)
    job_data = response.json()

    if job_data and job_data.get('jobs'):
        print(f"Found {len(job_data['jobs'])} jobs.")
        for job in job_data['jobs'][:5]: # Print first 5 jobs
            print(f"- {job['title']} at {job['company']} ({job['location']})")
    else:
        print("No jobs found or unexpected response structure.")

except requests.exceptions.HTTPError as errh:
    print(f"HTTP Error: {errh}")
except requests.exceptions.ConnectionError as errc:
    print(f"Error Connecting: {errc}")
except requests.exceptions.Timeout as errt:
    print(f"Timeout Error: {errt}")
except requests.exceptions.RequestException as err:
    print(f"An error occurred: {err}")

This Python script initiates a GET request, checks for HTTP errors, and then parses the JSON response to display job titles, companies, and locations. Successful execution confirms that your API key is valid and your application can communicate with the Careerjet API.

Common next steps

Once you've made your first successful API call, consider these next steps to build out your integration:

  1. Implement Pagination: For extensive job searches, you'll need to handle paginated results. Use the start_num and pagesize parameters to retrieve subsequent sets of job listings (Careerjet API pagination details).
  2. Refine Search Parameters: Explore additional parameters like contracttype, salarymin, salarymax, and radius to allow users to refine their job searches with more precision.
  3. Error Handling: Implement robust error handling to gracefully manage common API issues, such as rate limits, invalid parameters, or server errors. The API typically returns specific error codes and messages (Mozilla HTTP status codes reference).
  4. Data Storage and Caching: Decide whether to cache job data to reduce API calls and improve performance. Be mindful of Careerjet's terms regarding data retention and display.
  5. User Interface Integration: Design and develop the user interface for displaying job results, including search forms, job cards, and detailed job views.
  6. Rate Limit Management: Monitor your API usage to stay within the limits of your chosen plan. Implement exponential backoff or similar strategies to handle 429 Too Many Requests responses if necessary.
  7. Security Considerations: Ensure your API key is not exposed in client-side code. All API calls should ideally be made from a secure backend server.
  8. Monitor API Updates: Periodically check the Careerjet Partners API page for any updates, new features, or deprecations.

Troubleshooting the first call

If your initial API request doesn't return the expected results, consider these common troubleshooting steps:

  • Verify API Key (affid): Double-check that your API key is correctly included in the affid parameter and matches the one provided in your Careerjet partner account. An incorrect key will result in authentication errors.
  • Check user_ip Parameter: Ensure that the user_ip parameter is included and contains a valid IP address. While affid authenticates, user_ip is critical for rate limiting and geographic relevance, and its absence or an invalid value can cause issues.
  • Examine Request URL: Review the entire URL for typos, incorrect parameter names, or missing required parameters. Ensure URL encoding is correctly applied to parameter values (e.g., spaces in keywords should be %20).
  • Inspect API Response: If you receive an HTTP status code other than 200 OK, examine the response body for specific error messages. Careerjet's API will often provide a detailed explanation of what went wrong (Careerjet API error codes). Common errors include invalid parameters, unauthorized access, or rate limit exceeded.
  • Test with Minimal Parameters: Start with the absolute minimum required parameters (keywords, affid, user_ip) to isolate issues. Gradually add more parameters once the basic request is successful.
  • Review Rate Limits: If you're consistently getting 429 Too Many Requests errors, you might be exceeding your plan's rate limits. Pause your requests and try again after a short interval, or consider upgrading your plan (Careerjet API pricing tiers).
  • Check Network Connectivity: Ensure that your development environment has unrestricted internet access and can reach public.api.careerjet.net. Firewall rules or proxy settings can sometimes block outbound requests.
  • Consult Documentation and Examples: Refer to the Careerjet API reference documentation and provided code examples for your language to ensure your request structure aligns with the API's expectations.