TotalJobs APItotaljobs.com ↗
Access TotalJobs job listings via API. Search by keyword, location, and radius. Retrieve titles, salaries, companies, and full job descriptions.
What is the TotalJobs API?
The TotalJobs API provides 2 endpoints for querying UK job listings on totaljobs.com. The search_jobs endpoint accepts keyword, location, and radius parameters and returns paginated sets of up to 25 jobs per page, including title, company, salary, posting time, and snippet fields. The get_job_detail endpoint retrieves the full listing for any job URL, including structured description text and an apply link.
curl -X GET 'https://api.parse.bot/scraper/5e28ef95-23e9-48ef-9a2a-525932d8a6ee/search_jobs?page=1&query=software+engineer&radius=10&location=London' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace totaljobs-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.totaljobs_scraper_api import TotalJobs, NotFoundError
client = TotalJobs()
# Search for software engineer jobs in London with a 15-mile radius
for job in client.jobs.search(query="software engineer", location="London", radius=15, limit=5):
print(job.title, "|", job.company, "|", job.salary, "|", job.location)
# Take a single result and inspect its details
job = client.jobs.search(query="nurse", location="Manchester", limit=1).first()
if job:
print(job.title, job.url, job.posted_time)
# Demonstrate typed error handling
try:
for j in client.jobs.search(query="data analyst", location="Birmingham", limit=3):
print(j.title, j.company, j.snippet[:80] if j.snippet else "")
except NotFoundError as exc:
print(f"Search failed: {exc}")
print("exercised: jobs.search (multiple queries, locations, radius)")
Search for job listings on totaljobs.com by keyword and location. Returns paginated results with job titles, companies, locations, salaries, posting times, URLs, and description snippets. Each page returns up to 25 results. At least one of query or location should be provided for meaningful results.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (1-based) |
| query | string | Job title or keyword to search for (e.g. 'software engineer', 'nurse') |
| radius | integer | Search radius in miles from the location. Common values: 5, 10, 15, 20, 25, 50. |
| location | string | Location to search in (e.g. 'London', 'Manchester', 'Birmingham') |
{
"type": "object",
"fields": {
"jobs": "array of job objects with keys: title, company, location, salary, posted_time, url, snippet",
"has_next": "boolean, whether more pages of results exist",
"current_page": "integer, the current page number",
"total_results": "integer or null, total number of matching jobs"
},
"sample": {
"data": {
"jobs": [
{
"url": "https://www.totaljobs.com/job/staff-software-engineer/stepstone-uk-job107319597",
"title": "Staff Software Engineer",
"salary": "Non Variable Salary",
"company": "Stepstone UK",
"snippet": "Working closely with software engineers, machine learning engineers, data scientists...",
"location": "Southwark, South East London (SE1), SE1 0TA",
"posted_time": "3 weeks ago"
}
],
"has_next": true,
"current_page": 1,
"total_results": 1118
},
"status": "success"
}
}About the TotalJobs API
Searching for Jobs
The search_jobs endpoint accepts three optional filters: query (job title or keyword), location (city or region within the UK), and radius (distance in miles, with typical values of 5, 10, 25, or 50). At least one of query or location should be supplied. Results are paginated at 25 per page using the page parameter. Each response includes a jobs array where every object carries title, company, location, salary, posted_time, url, and snippet fields. The response also returns current_page, has_next (boolean), and total_results (integer or null when unavailable).
Retrieving Job Details
The get_job_detail endpoint takes a single required input: the full url of a TotalJobs listing, typically obtained from a search_jobs result. It returns a detailed object including title, company, salary, location, job_type, posted_date, apply_url, description_html, and description_text. The description_html and description_text fields both carry the full job description, giving you flexibility in how you process or display the content.
Coverage and Scope
All data covers UK-based listings on totaljobs.com. Location filtering works at the city or region level; the radius parameter sharpens results around a specific point. Salary and posting-time fields are returned as strings exactly as they appear on the listing — some listings omit salary information, in which case the field may be empty or null.
The TotalJobs API is a managed, monitored endpoint for totaljobs.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when totaljobs.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official totaljobs.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Aggregate UK job market data by keyword and region using
search_jobswithqueryandlocationfilters - Build a salary benchmarking tool by collecting the
salaryfield across many roles and locations - Monitor new listings for a specific job title by polling
search_jobsand trackingposted_time - Enrich a job board by fetching
description_textandapply_urlviaget_job_detail - Identify hiring trends by counting listings per company across a region
- Automate candidate alerts by comparing
total_resultsover time for a saved query
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TotalJobs have an official developer API?+
What does `get_job_detail` return beyond what `search_jobs` provides?+
search_jobs returns a brief snippet, a single salary string, and basic metadata. get_job_detail adds job_type, posted_date, apply_url, description_html, and description_text — the full job description and the direct application link, which are not available in the search result objects.How does pagination work in `search_jobs`?+
has_next boolean indicates whether additional pages exist. Increment the page parameter (1-based) to retrieve subsequent pages. The total_results field gives the total match count when the source provides it, but it may be null for some queries.Does the API cover jobs outside the UK?+
location parameter and radius filter operate within the UK only. You can fork this API on Parse and revise it to point to a different jobs source with international coverage.Can I filter by job type (full-time, contract, part-time) in `search_jobs`?+
search_jobs endpoint supports filtering by query, location, and radius only. Job type is returned as a field in get_job_detail but cannot be used as a search filter. You can fork the API on Parse and revise it to add a job_type filter parameter.