hh APIhh.uz ↗
Search vacancies, employers, and geographic regions on HeadHunter Uzbekistan (hh.uz). Filter by location, salary, experience, and schedule via 6 endpoints.
What is the hh API?
The hh.uz API provides access to HeadHunter Uzbekistan's job market through 6 endpoints covering vacancy search, employer profiles, and geographic data. search_vacancies accepts filters like area, salary, schedule, and employment type, returning paginated results with vacancy ID, employer name, salary text, and address. Companion endpoints deliver full vacancy descriptions, key skills, employer details, and a structured tree of professional roles.
curl -X GET 'https://api.parse.bot/scraper/07bbb703-b142-467f-b860-09067fa58849/search_vacancies?area=2759&page=0&text=Python&order_by=relevance&per_page=20&schedule=fullDay&employment=full&experience=noExperience' \ -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 hh-uz-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.
"""HH.uz Job Search — find vacancies, employers, and browse roles in Uzbekistan."""
from parse_apis.HH_uz_Job_Search_API import HHuz, Experience, Schedule, OrderBy, ResourceNotFound
client = HHuz()
# Search remote Python vacancies for experienced developers, sorted by salary
for vacancy in client.vacancies.search(
text="Python",
experience=Experience.BETWEEN_3_AND_6,
schedule=Schedule.REMOTE,
order_by=OrderBy.SALARY_DESC,
limit=5,
):
print(vacancy.name, vacancy.salary_text, vacancy.address)
# Drill into the first result for full details (description, skills)
vacancy = client.vacancies.search(text="data engineer", limit=1).first()
if vacancy:
detail = vacancy.refresh()
print(detail.name, detail.experience, detail.location)
for skill in detail.key_skills[:5]:
print(f" skill: {skill}")
# Search employers and get details via constructible Employer
employer = client.employers.search(text="bank", limit=1).first()
if employer:
full = employer.refresh()
print(full.name, full.site_url, full.open_vacancies)
# Typed error handling: catch ResourceNotFound for a bad employer ID
try:
bad = client.employer(id="9999999999").refresh()
except ResourceNotFound as exc:
print(f"Not found: {exc}")
# Browse role categories
for cat in client.role_categories.list(limit=3):
print(cat.name, [r.name for r in cat.roles[:2]])
print("exercised: vacancies.search / vacancy.refresh / employers.search / employer.refresh / role_categories.list")
Search for job vacancies on hh.uz with filters for keyword, location, experience, employment type, and more. Returns paginated results. Each result includes vacancy ID, title, employer info, salary text, and address. Use vacancy IDs from results to fetch full details via get_vacancy_detail.
| Param | Type | Description |
|---|---|---|
| area | string | Area ID (e.g. 2759 for Tashkent, 97 for Uzbekistan) |
| page | integer | Page number (0-based) |
| text | string | Keyword search query |
| salary | integer | Minimum salary filter |
| order_by | string | Sort order for results |
| per_page | integer | Items per page (max 100) |
| schedule | string | Work schedule filter |
| employment | string | Employment type filter |
| experience | string | Experience level filter |
| only_with_salary | boolean | Only show vacancies with salary specified |
{
"type": "object",
"fields": {
"page": "integer current page number",
"found": "integer total number of matching vacancies",
"items": "array of vacancy objects with id, name, employer, salary_text, address, url",
"pages": "integer total number of pages",
"per_page": "integer items per page"
},
"sample": {
"data": {
"page": 0,
"found": 196,
"items": [
{
"id": "133953871",
"url": "https://hh.uz/vacancy/133953871",
"name": "Senior Backend / Fullstack Developer (Python / Node.js)",
"address": "Tashkent",
"employer": {
"id": "11215262",
"name": "OOO PROSIGHT DEV"
},
"salary_text": null
}
],
"pages": 10,
"per_page": 20
},
"status": "success"
}
}About the hh API
Vacancy Search and Detail
search_vacancies accepts up to eight filter parameters — including text for keyword search, area for a region ID, salary for a minimum salary floor, and order_by for sort order (relevance, publication_time, salary_desc, salary_asc). Pagination is zero-based via page and per_page (up to 100 items). Each item in the items array carries id, name, employer, salary_text, address, and url. Pass any returned id to get_vacancy_detail to retrieve the full picture: description, key_skills as an array of strings, experience level, and structured employer and location fields.
Employers and Professional Roles
search_employers takes a required text query plus an optional area filter and returns paginated employer objects with id, name, and url. To get depth on a specific company, get_employer_detail returns site_url, description, and open_vacancies count alongside the basic identifiers. The get_professional_roles endpoint requires no parameters and returns a full category tree — each category has id, name, and a roles array — useful for building filter UIs or mapping role taxonomies.
Geographic Coverage
get_areas returns the complete region hierarchy when called without arguments: a nested tree of countries and cities, each node carrying id, name, parent_id, and a child areas array. Supplying an area_id (for example 97 for Uzbekistan or 2759 for Tashkent) scopes the response to that subtree. Area IDs from this endpoint feed directly into the area parameter on search_vacancies and search_employers.
The hh API is a managed, monitored endpoint for hh.uz — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when hh.uz 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 hh.uz 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 Uzbekistan job listings filtered by city and minimum salary for a local job board
- Track the number of open vacancies per employer over time using
get_employer_detail'sopen_vacanciesfield - Build a role taxonomy browser from
get_professional_rolescategories and roles - Populate a location picker with the full region tree from
get_areasfor a job-search app - Extract
key_skillsarrays fromget_vacancy_detailto analyze in-demand skills by industry - Monitor new vacancies for a specific employer by combining
search_employersandsearch_vacancieswith the employer's area
| 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 hh.uz have an official developer API?+
What does `search_vacancies` return and how granular is salary data?+
search_vacancies returns a salary_text string for each vacancy — a human-readable display value rather than structured numeric fields. The same salary_text field appears in get_vacancy_detail. There are no separate salary_from, salary_to, or currency fields in the current response shape, so salary comparisons require parsing the text string yourself.Is resume or applicant data available through this API?+
How does pagination work across endpoints?+
search_vacancies and search_employers use zero-based pagination. The page parameter sets the current page (default 0) and responses include pages (total page count), per_page, and found (total matching records). per_page maxes out at 100 for vacancies. get_areas and get_professional_roles return complete datasets in a single call with no pagination.Does the API cover job listings outside Uzbekistan?+
get_areas endpoint does include region nodes for other countries (for example, area ID 113 for Russia appears in the full tree), but vacancy and employer data reflects hh.uz listings. Coverage of non-Uzbekistan markets is incidental rather than guaranteed. You can fork this API on Parse and revise it to point at hh.ru or another regional HeadHunter domain for broader geographic scope.