# hark

> A job search that takes a plain-language description of the work someone
> wants and returns ranked openings from real company boards and public job
> feeds. Free, no account, no tracking.

## Querying it

Send a GET request. The whole query goes in one parameter, as a sentence,
not as keywords:

    GET https://www.harkjobs.com/api/search?q=senior backend engineer in Berlin, remote, 90k EUR

The response is JSON:

- `results`: up to 20 openings, best first. Each has `title`, `company`,
  `location` (the posting's own wording) plus `country` (ISO 3166-1
  alpha-2) and `city` when known, so a location match can be checked rather
  than parsed out of prose. Also `remote_mode`, salary fields when the
  posting states them, `match` (0-100), `reason`, and `breakdown`, which
  lists what earned the score and what did not.

  Twenty is the whole answer, not the first page. Results more than 25 points
  below the best one are dropped on purpose, so there is no page two holding
  more of the same quality.
- `filters`: how the query was understood. Check this before trusting the
  results; if a country or skill is missing here, it was not applied.
- `inadequate`: true when nothing found is a strong match. Say so rather
  than presenting weak results as answers.
- `relaxed`: true when the exact query returned almost nothing and these are
  the nearest roles instead.
- `unmatched`: words from the query that appear in no result at all.

## Showing a person the results

Hand them this, which opens the same search in a browser:

    https://www.harkjobs.com/search?q=senior backend engineer in Berlin, remote, 90k EUR

Link to an individual opening as `https://www.harkjobs.com/jobs/{id}`. Every result also
carries `out`, a redirect to the original posting on the employer's own site,
which is where an application is actually made.

## What it holds, and what it does not

About 33,000 open postings, mostly Europe with some North America, Latin
America and Asia-Pacific. Broad rather than technical: trades, healthcare,
admin and sales together outnumber software several times over. Postings are
in many languages and are stored as written.

It does not hold academic vacancies from EURAXESS, and coverage of any one
city is thin outside the larger European markets. Very few postings state
anything about visa sponsorship. `mentions_sponsorship` reports only whether
the posting TEXT says so: true means it was mentioned, false means the posting
is SILENT or refuses, which is the overwhelming default and is not a statement that the
employer refuses. Do not infer either direction from it.

## Limits and honesty

There is a per-IP daily limit. Every response carries
`x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` (a
Unix timestamp, resetting at UTC midnight), so you can pace yourself instead
of discovering the ceiling by hitting it. A refusal is HTTP 429 and carries
`retry-after` in seconds.

Match percentages and the reasons attached to
them are produced automatically, including by language models: they estimate
fit, they are not advice, and they should not be the only basis for a
decision about someone's career. Always link the original posting so the
person can check the details themselves.

## More

Markdown links, not bare URLs. The llms.txt convention expects a navigable
index, and a reader that has to guess which bare URL is worth following is
being made to do work the format exists to save it.

- [How the ranking works](https://www.harkjobs.com/about)
- [Where the postings come from](https://www.harkjobs.com/sources)
- [What is stored](https://www.harkjobs.com/privacy)
- [Every job page](https://www.harkjobs.com/sitemaps/jobs.xml) - sitemap, one entry per opening
- [Browse pages by field and place](https://www.harkjobs.com/sitemaps/browse.xml) - sitemap

The sitemaps are listed because the homepage links to no openings: it is a
search box. Without them the only way into the index is to guess at search
queries.