NHS Jobs Scraper

Job adverts from NHS Jobs (jobs.nhs.uk), the UK's public-sector health job board — ~12,800 live adverts from NHS trusts, GP practices and partner organisations: title, employer, town and postcode, salary parsed with its period, date posted, closing date, contract type and working pattern. With includeDetails, the full advert too: summary, main duties, description, person specification (essential and desirable, by category), pay scheme, employer address and website, contact name / phone / email, DBS requirement.

HTTP only, no login, no key, no browser. 10 jobs per page; every page of every search is reachable.

What it is for

• Vacancy monitoring by role, place and radius, on a schedule.
• Salary and band research — every row has the salary as shown and parsed, with the period, so hourly and annual are never mixed.
• Employer tracking — filter by employer, keep the rows.

Input

field	what it does
searchTerms	nurse, pharmacist, data analyst. Empty = every advert.
locations + distanceMiles	Town, city or postcode, with a 5–100 mile radius.
contractTypes, workingPatterns, payBands, staffGroups, salaryFrom/To, employer, sortBy	Filters, each verified against the rows it returns.
includeDetails	One extra request per job for the full advert.
maxItems, maxConcurrency, minRequestInterval, proxyConfiguration	Limits.

Targets are searchTerms × locations; each gets its own SEARCH_SUMMARY.

Six things about this site worth knowing before you trust a run

1. Three different "nothing" pages

A nonsense keyword answers "No result found for …" with zero cards. A place the site cannot resolve answers a 19 KB page with an empty heading and no count — not "no results", a page it could not build. And between 7:00 and 9:30 UK time the whole site answers a 228 KB planned-downtime page with HTTP 200. The Actor tells them apart: no_matches, location_not_recognised, and site_maintenance (with the notice text) — never a parser error, never a retry.

2. Past the last page is empty; far past it is a 500

Page 46 of a 45-page search is a clean empty page. Page 9,999 is an HTTP 500. The Actor computes the last page from the site's own "N jobs found" and never asks beyond it.

3. Multi-value filters are comma-joined; the natural encoding is a 500

contractType=Bank,Locum works. contractType=Bank&contractType=Locum answers HTTP 500, as does sort=zz, and an empty distance= turns a search into the unknown-location page. Every enum is validated here first, with the site's vocabulary in the error, and nothing empty is ever sent.

4. distanceMiles narrows a place, not a region

Nurse jobs within 1 / 5 / 10 / 20 / 50 / 100 miles of Manchester: 12 / 75 / 170 / 248 / 1,080 / 2,172. Within 5 or 100 miles of London: 450 either way — London resolves to a region, and a region has no radius. The summary carries the distance it sent so a flat count is visible.

5. Salary is free text in five shapes

"£31,049 to £37,796 a year", "£12.71 an hour", "£397 a day", "£62.50 a session", "Depends on experience". Rows carry salaryText as shown plus salaryMin, salaryMax, salaryPeriod (year / hour / day / session) and salaryDependsOnExperience. Hourly rates are not annualised.

6. The advert HTML is malformed and duplicated

The description sits in a <p> nested inside a <p>, so an id lookup returns an empty string; and every address line appears twice (mobile and desktop copies). The detail parser slices the raw HTML by its headings and takes each heading's first occurrence.

Output

• JOB — jobReference, url, title, employer, location, town, postcode, salaryText, salaryMin, salaryMax, salaryPeriod, salaryCurrency, salaryDependsOnExperience, datePosted, closingDate, contractType, workingPatterns, query, locationSearched, resultPosition, pageFound; with details: summary, mainDuties, aboutEmployer, description, personSpecification, payScheme, jobLocationsText, employerAddress, employerWebsite, contactName, contactJobTitle, contactEmail, contactPhone, dbsCheckRequired.
• SEARCH_SUMMARY — one per target: totalResults, jobsReturned, pagesFetched, stoppedReason, distanceMiles, filters, detailsFetched, detailsFailed, rowsWithSalary, rowsDependsOnExperience, contractTypeCounts, salaryPeriodCounts.
• ERROR — invalid_input, site_maintenance, page_shape_changed, upstream_error, fetch_failed, with detail.

Known limits

• salaryFrom/salaryTo are applied by the site with its own conversion of hourly and daily rates; the rows show what it returned.
• Welsh-language adverts are served in English by default; the Welsh text is not fetched.
• The planned-downtime window (07:00–09:30 UK) returns no data; schedule runs outside it.