Tes Jobs Scraper

Scrape teaching, school-leadership, and education-support job vacancies from Tes.com (Times Educational Supplement) — the UK's largest education jobs board, also listing thousands of international school vacancies worldwide. Search by keyword, subject, position, workplace type, contract type/term, or fetch exact vacancies by ID or URL. Every job includes the full description, employer contact details, and salary information.

What this actor does

• Three modes: search (keyword + filter search), byVacancyIds (exact lookup by numeric vacancy ID), byUrls (exact lookup by job page URL)
• Rich filters: position/role, subject, school/workplace type, contract type (full/part time), contract term (permanent/fixed term/temporary/supply/casual/maternity cover), sort order (relevance/date/distance), and optional location-radius search
• Full job detail: complete HTML-stripped job description, employer profile (address, phone, website, logo), application contact (email/phone/direct-apply URL), exact position/subject/workplace taxonomy tags, and geo-coordinates
• International coverage: the same search covers UK state/independent schools plus international schools across the Middle East, Asia, and Europe
• Empty fields are omitted — every record only contains data that was actually found

Output per job

Field	Description
vacancyId	Numeric Tes vacancy ID
title	Job title
employerName, employerId	Hiring school/organisation
displayLocation	Human-readable location
position	Primary normalized position/role (e.g. "Teacher", "Headteacher")
positions[]	All position/role tags on the job
subjects[]	Subject tags (e.g. "Mathematics")
workplaces[]	School/workplace type tags (e.g. "Secondary", "Special Education" — a job can carry more than one, e.g. an all-through school)
contractTypes[], contractTerms[]	Full/Part Time; Permanent/Fixed Term/etc.
displaySalary, salaryRange	Salary as advertised
shortDescription, description	Plain-text job description (short teaser + full detail)
advertStartDate, advertEndDate, applicationCloseDate	Key dates (ISO 8601)
applicationUrl, applicationEmail, applicationPhone, applicationContactName	How to apply
employerWebsite, employerPhone, employerAddress, employerCity, employerCountry	Employer contact/location
employerLogoUrl, employerHeaderImageUrl	Employer branding images
latitude, longitude	Employer geo-coordinates
isPromoted, isQuickApply	Listing flags
vacancyUrl	Canonical job page URL
recordType	Always "job"
scrapedAt	UTC scrape timestamp
sourceUrl	Same as vacancyUrl

Input

Field	Type	Default	Description
mode	select	search	search / byVacancyIds / byUrls
keywords	string	teacher	Free-text search query (mode=search)
positions	array (enum)	–	Filter by role, e.g. ["Teacher", "Headteacher"]
subjects	array (enum)	–	Filter by subject, e.g. ["Mathematics"]
workplaces	array (enum)	–	Filter by school type, e.g. ["Primary", "Secondary"]
contractTypes	array (enum)	–	Full Time / Part Time
contractTerms	array (enum)	–	Permanent / Fixed Term / Casual / Maternity Cover / Temporary / Supply
sortBy	select	relevance	relevance / date / distance
locationName, locationLat, locationLon, locationDistance, distanceUnit	–	–	Optional radius search around a coordinate
vacancyIds	array	–	Numeric vacancy IDs (mode=byVacancyIds)
startUrls	array	–	Job page URLs (mode=byUrls)
fetchFullDescription	boolean	true	Fetch each job's full detail page for the richer field set above
maxItems	integer	50	Maximum number of jobs to return (1–2000)

Example: UK maths teacher vacancies, permanent, full-time

{
  "mode": "search",
  "keywords": "maths",
  "subjects": ["Mathematics"],
  "contractTypes": ["Full Time"],
  "contractTerms": ["Permanent"],
  "sortBy": "date",
  "maxItems": 50
}

Example: fetch specific vacancies by ID

{
  "mode": "byVacancyIds",
  "vacancyIds": [2338332, 2338743]
}

Example: fetch specific vacancies by URL

{
  "mode": "byUrls",
  "startUrls": ["https://www.tes.com/jobs/vacancy/maths-teacher-north-tyneside-2338332"]
}

Use cases

• Education recruitment agencies monitoring new teaching vacancies by subject/region
• Job aggregators syndicating UK & international teaching jobs
• Labour-market researchers tracking teacher demand by subject, region, or contract type
• School HR / MAT teams benchmarking salaries and vacancy volumes against competitors

FAQ

Does this require login or an API key? No. Tes.com job search and job listings are public; no account, cookies, or API key are needed.

What locations does it cover? Tes.com is UK-based but lists thousands of international school vacancies (Middle East, Asia, Europe) in the same search index — no separate country switch is needed.

Can I search by salary? Salary is only available as free text on Tes (e.g. "Up to £44,000 per annum") — there's no structured numeric salary filter upstream, so displaySalary/salaryRange are provided as text fields rather than a filterable numeric range.

How fresh is the data? Every run queries Tes.com's live job-search API directly — there is no caching layer.

Why does fetchFullDescription matter? The search-results API only returns a short summary. Enabling fetchFullDescription (on by default) fetches each job's detail page for the complete description, employer contact details, and taxonomy tags (position/subject/workplace) — at the cost of one extra request per job. Detail pages are fetched concurrently (bounded, with automatic retries on rate-limiting), but very large maxItems values (into the thousands) with fetchFullDescription enabled will take noticeably longer to finish than a search-only run, especially if Tes.com starts rate-limiting the run. Set fetchFullDescription: false for the fastest large-scale runs when the summary fields are enough.