Metadata-Version: 2.4
Name: signalsapi
Version: 0.1.0
Summary: Keyless Python client for the public SignalsAPI reads — hiring-requisition search and the data-provenance statement
License: MIT
Project-URL: Homepage, https://jobsapi.signalsapi.com
Project-URL: Documentation, https://jobsapi.signalsapi.com/docs
Keywords: hiring,jobs,requisitions,ats,api-client
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# signalsapi (Python)

Keyless Python client for the two public SignalsAPI reads. No API key, no dependencies,
no response models — install it and the next line returns live data.

## Install

```bash
pip install signalsapi
```

## Use

```python
import signalsapi

# The data-provenance guarantee — what this plane sources, and what it never serves.
print(signalsapi.compliance()["guarantee"][0])

# Who is hiring for {role, geo}. Real rows, no credentials.
result = signalsapi.reqs_search(role="staff engineer", geo="United States", limit=5)
for company in result["companies"]:
    print(company["company_id"], company["pulse"]["open_req_count"]["value"])
```

Both calls return the response JSON verbatim — this client transcribes no response
models, so what the API returns is what you get. Any non-2xx raises
`urllib.error.HTTPError`.

## API

| Function | Endpoint | Parameters |
|---|---|---|
| `compliance()` | `GET /compliance` | — |
| `reqs_search()` | `GET /sandbox/reqs/search` | `role`, `geo`, `since`, `limit` (all optional) |

- `role` — full-text query over the raw posting title; every word must match.
- `geo` — country name, e.g. `"United States"`. A country that cannot resolve is a 422.
- `since` — ISO-8601 lower bound on when a req was first seen, passed through as written.
- `limit` — companies per page, capped by the sandbox demo ceiling.

Both accept `base_url` and `timeout`. There is no paging: a non-null `next_cursor` in the
response says the corpus continues past what a keyless call may read, and walking it needs
a key — see <https://jobsapi.signalsapi.com/docs>.

## Base URL

`https://jobsapi.signalsapi.com/api/v1` — the gateway vhost, and the only base that serves
these routes publicly. `api.signalsapi.com` and the apex 404 them; `ss.signalsapi.com`
answers 401 before the API is reached.

## Scope

Two reads, deliberately. This is the surface an evaluator can call inside one conversation
without signing up; the paid contract is a different, key-gated client. Keeping this one
schema-free is what bounds the cost of maintaining it by hand (signalsapi-3791/-4173).

MIT licensed.
