remote-jobs-api 1.1.0__tar.gz

remote_jobs_api-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nova (earnnova7)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

remote_jobs_api-1.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: remote-jobs-api
+Version: 1.1.0
+Summary: Normalized remote-job data across 5 boards — one endpoint, one schema, skill fit-score
+Author-email: Nova <earnnova@tten.no>
+License: MIT
+Project-URL: Homepage, https://github.com/earnnova-dev/remote-jobs-api
+Project-URL: Documentation, https://earnnova-dev.github.io/remote-jobs-api/
+Keywords: jobs,remote,api,scraping,feed,aggregator,data
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Remote Jobs API
+
+**Live, normalized remote-job data across 5 boards — one clean endpoint, one schema.**
+
+Stop scraping Remotive / RemoteOK / We Work Remotely / Jobicy / Hacker News
+yourself. This API pulls them, normalizes every listing into a single
+schema, dedupes, and hands you structured JSON (or CSV) — with an optional
+**0-100 skill fit-score** for ranking.
+
+Built for:
+- Job boards & aggregator sites
+- Recruiter and ATS tooling
+- Lead-gen and market research
+- **AI agents** that need structured job data in one call
+
+## Why it's different
+- **One schema, every board.** No per-board adapters on your side.
+- **No session scraping.** Reads public job-board endpoints — your data never
+  leaves their servers, no browser, no account.
+- **Self-hostable.** Stdlib-only Python (zero dependencies). Run it on a
+  laptop, a $5 VPS, or containerize it with the included Dockerfile.
+- **Deterministic fit scoring.** No hidden LLM, no black box — reproducible
+  ranking you can reason about and unit-test.
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Status + live job count |
+| GET | `/v1/jobs/sources` | Available boards |
+| GET | `/v1/jobs` | Normalized job listings |
+
+### GET /v1/jobs
+
+Query params:
+
+| Param | Type | Notes |
+|-------|------|-------|
+| `skills` | string | Comma-separated keywords → adds `fit_score`, ranks best-first |
+| `source` | string | `remotive` / `remoteok` / `jobicy` / `wwr` / `hn` |
+| `limit` | int | 1-500 (default 50) |
+| `min_score` | int | 0-100, filter by fit (needs `skills`) |
+| `format` | string | `json` (default) or `csv` |
+
+### Example
+
+```bash
+curl "https://<your-host>/v1/jobs?skills=python,backend,api&limit=3"
+```
+
+```json
+{
+  "count": 3,
+  "generated_at": 1790433192,
+  "jobs": [
+    {
+      "id": "94516b10164d3c70",
+      "title": "Senior Backend Developer (Python)",
+      "company": "Proxify AB",
+      "url": "https://weworkremotely.com/remote-jobs/proxify-ab-senior-backend-developer-python-10",
+      "location": "Anywhere in the World",
+      "category": "Back-End Programming",
+      "source": "wwr",
+      "published": "Tue, 15 Sep 2026 09:01:36 +0000",
+      "fit_score": 80
+    }
+  ]
+}
+```
+
+## Run it yourself
+
+Zero runtime dependencies — it's pure Python stdlib.
+
+**Option A — CLI (query the feed directly, no server needed):**
+
+```bash
+pip install remote-jobs-api
+remote-jobs-api --skills python,api --limit 5
+remote-jobs-api --source wwr --format csv
+remote-jobs-api --help
+```
+
+**Option B — HTTP API server (self-host):**
+
+```bash
+pip install remote-jobs-api
+remote-jobs-api --serve --port 8321        # or: python -m remote_jobs_api.server
+```
+
+Or from source / Docker:
+
+```bash
+git clone https://github.com/earnnova-dev/remote-jobs-api
+cd remote-jobs-api
+python3 -m remote_jobs_api.server          # listens on :8321
+```
+
+```bash
+docker build -t remote-jobs-api .
+docker run -p 8321:8321 remote-jobs-api
+```
+
+Env vars:
+- `PORT` (default `8321`)
+- `RJA_CACHE_TTL` (default `300` s) — how long to cache upstream fetches
+
+## Testing
+
+Offline unit tests (no network): `python -m pytest`.
+
+## Pricing (indicative, for a hosted tier)
+
+| Plan | Price | Includes |
+|------|-------|----------|
+| **Free** | $0 | 100 calls/mo, all boards, 50 results/req |
+| **Pro** | $19/mo | 10k calls/mo, CSV, min_score, higher limits |
+| **Team** | $49/mo | 100k calls/mo, SLA, webhooks (soon) |
+
+> Self-hosted = free, MIT. The paid tier is the hosted, always-on,
+> high-rate-limit version — the same engine, managed for you.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Data & compliance
+
+This API only reads public, no-auth job-board endpoints and returns data
+exactly as those boards publish it. It does not store your personal data,
+does not scrape authenticated sessions, and does not resell any board's
+proprietary content beyond what is publicly viewable.

remote_jobs_api-1.1.0/README.md

@@ -0,0 +1,132 @@
+# Remote Jobs API
+
+**Live, normalized remote-job data across 5 boards — one clean endpoint, one schema.**
+
+Stop scraping Remotive / RemoteOK / We Work Remotely / Jobicy / Hacker News
+yourself. This API pulls them, normalizes every listing into a single
+schema, dedupes, and hands you structured JSON (or CSV) — with an optional
+**0-100 skill fit-score** for ranking.
+
+Built for:
+- Job boards & aggregator sites
+- Recruiter and ATS tooling
+- Lead-gen and market research
+- **AI agents** that need structured job data in one call
+
+## Why it's different
+- **One schema, every board.** No per-board adapters on your side.
+- **No session scraping.** Reads public job-board endpoints — your data never
+  leaves their servers, no browser, no account.
+- **Self-hostable.** Stdlib-only Python (zero dependencies). Run it on a
+  laptop, a $5 VPS, or containerize it with the included Dockerfile.
+- **Deterministic fit scoring.** No hidden LLM, no black box — reproducible
+  ranking you can reason about and unit-test.
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Status + live job count |
+| GET | `/v1/jobs/sources` | Available boards |
+| GET | `/v1/jobs` | Normalized job listings |
+
+### GET /v1/jobs
+
+Query params:
+
+| Param | Type | Notes |
+|-------|------|-------|
+| `skills` | string | Comma-separated keywords → adds `fit_score`, ranks best-first |
+| `source` | string | `remotive` / `remoteok` / `jobicy` / `wwr` / `hn` |
+| `limit` | int | 1-500 (default 50) |
+| `min_score` | int | 0-100, filter by fit (needs `skills`) |
+| `format` | string | `json` (default) or `csv` |
+
+### Example
+
+```bash
+curl "https://<your-host>/v1/jobs?skills=python,backend,api&limit=3"
+```
+
+```json
+{
+  "count": 3,
+  "generated_at": 1790433192,
+  "jobs": [
+    {
+      "id": "94516b10164d3c70",
+      "title": "Senior Backend Developer (Python)",
+      "company": "Proxify AB",
+      "url": "https://weworkremotely.com/remote-jobs/proxify-ab-senior-backend-developer-python-10",
+      "location": "Anywhere in the World",
+      "category": "Back-End Programming",
+      "source": "wwr",
+      "published": "Tue, 15 Sep 2026 09:01:36 +0000",
+      "fit_score": 80
+    }
+  ]
+}
+```
+
+## Run it yourself
+
+Zero runtime dependencies — it's pure Python stdlib.
+
+**Option A — CLI (query the feed directly, no server needed):**
+
+```bash
+pip install remote-jobs-api
+remote-jobs-api --skills python,api --limit 5
+remote-jobs-api --source wwr --format csv
+remote-jobs-api --help
+```
+
+**Option B — HTTP API server (self-host):**
+
+```bash
+pip install remote-jobs-api
+remote-jobs-api --serve --port 8321        # or: python -m remote_jobs_api.server
+```
+
+Or from source / Docker:
+
+```bash
+git clone https://github.com/earnnova-dev/remote-jobs-api
+cd remote-jobs-api
+python3 -m remote_jobs_api.server          # listens on :8321
+```
+
+```bash
+docker build -t remote-jobs-api .
+docker run -p 8321:8321 remote-jobs-api
+```
+
+Env vars:
+- `PORT` (default `8321`)
+- `RJA_CACHE_TTL` (default `300` s) — how long to cache upstream fetches
+
+## Testing
+
+Offline unit tests (no network): `python -m pytest`.
+
+## Pricing (indicative, for a hosted tier)
+
+| Plan | Price | Includes |
+|------|-------|----------|
+| **Free** | $0 | 100 calls/mo, all boards, 50 results/req |
+| **Pro** | $19/mo | 10k calls/mo, CSV, min_score, higher limits |
+| **Team** | $49/mo | 100k calls/mo, SLA, webhooks (soon) |
+
+> Self-hosted = free, MIT. The paid tier is the hosted, always-on,
+> high-rate-limit version — the same engine, managed for you.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Data & compliance
+
+This API only reads public, no-auth job-board endpoints and returns data
+exactly as those boards publish it. It does not store your personal data,
+does not scrape authenticated sessions, and does not resell any board's
+proprietary content beyond what is publicly viewable.

remote_jobs_api-1.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "remote-jobs-api"
+version = "1.1.0"
+description = "Normalized remote-job data across 5 boards — one endpoint, one schema, skill fit-score"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Nova", email = "earnnova@tten.no" }]
+keywords = ["jobs", "remote", "api", "scraping", "feed", "aggregator", "data"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/earnnova-dev/remote-jobs-api"
+Documentation = "https://earnnova-dev.github.io/remote-jobs-api/"
+
+[project.scripts]
+remote-jobs-api = "remote_jobs_api.cli:main"
+
+[tool.setuptools]
+packages = ["remote_jobs_api"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

remote_jobs_api-1.1.0/remote_jobs_api/__init__.py

@@ -0,0 +1,2 @@
+"""Remote-Jobs Data API — normalized remote job listings as a product."""
+__version__ = "1.1.0"

remote_jobs_api-1.1.0/remote_jobs_api/__main__.py

@@ -0,0 +1,2 @@
+from .server import main
+main()

remote_jobs_api-1.1.0/remote_jobs_api/cli.py

@@ -0,0 +1,74 @@
+"""remote-jobs-api CLI — query the normalized feed without running a server.
+
+Usage:
+  remote-jobs-api --skills python,api --limit 5
+  remote-jobs-api --source wwr --format csv
+  remote-jobs-api --serve --port 8321        # run the HTTP API
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import json
+import sys
+
+from . import __version__, feed
+from .feed import SOURCES
+
+
+def _print_csv(jobs, file):
+    buf = io.StringIO()
+    cols = ["id", "title", "company", "location", "salary",
+            "category", "source", "published", "fit_score", "url"]
+    w = csv.DictWriter(buf, fieldnames=cols, extrasaction="ignore")
+    w.writeheader()
+    for j in jobs:
+        w.writerow(j)
+    file.write(buf.getvalue())
+
+
+def _run_query(args) -> int:
+    jobs = feed.filter_and_rank(
+        feed.collect(),
+        skills=args.skills or None,
+        source=args.source,
+        min_score=args.min_score,
+    )[: max(1, min(500, args.limit))]
+
+    if args.format == "csv":
+        _print_csv(jobs, sys.stdout)
+    else:
+        print(json.dumps(
+            {"count": len(jobs), "query": vars(args), "jobs": jobs},
+            ensure_ascii=False, indent=2,
+        ))
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="remote-jobs-api",
+        description="Normalized remote-job data from 5 boards: " + ", ".join(SOURCES),
+    )
+    p.add_argument("--version", action="version", version=f"remote-jobs-api {__version__}")
+    p.add_argument("--skills", help="comma-separated keywords for fit scoring")
+    p.add_argument("--source", choices=SOURCES, help="restrict to one board")
+    p.add_argument("--limit", type=int, default=50, help="max results (1-500, default 50)")
+    p.add_argument("--min-score", type=int, help="minimum fit_score (needs --skills)")
+    p.add_argument("--format", choices=["json", "csv"], default="json")
+    p.add_argument("--serve", action="store_true", help="run the HTTP API server")
+    p.add_argument("--port", type=int, default=8321)
+    args = p.parse_args(argv)
+
+    if args.serve:
+        import os
+        os.environ["PORT"] = str(args.port)
+        from .server import main as serve_main
+        serve_main()
+        return 0
+    return _run_query(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

remote_jobs_api-1.1.0/remote_jobs_api/feed.py

@@ -0,0 +1,312 @@
+"""Remote-Jobs Data API — normalized feed layer.
+
+Stdlib-only. Pulls live remote-job listings from public job-board endpoints
+that require no auth, normalizes them into ONE schema, and exposes them for
+the HTTP API. This is the same feed engine as GigWatch, repackaged as a data
+product.
+
+Public sources (no key, no account):
+  - remotive   https://remotive.com/api/remote-jobs
+  - remoteok   https://remoteok.com/api
+  - jobicy     https://jobicy.com/api/v2/remote-jobs
+  - wwr        https://weworkremotely.com/remote-jobs.rss
+  - hn         HN "Who is Hiring?" (Algolia, monthly megathread)
+"""
+from __future__ import annotations
+
+import hashlib
+import html
+import json
+import re
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, asdict, field
+from typing import Any, Dict, List, Optional
+
+UA = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (compatible; RemoteJobsAPI/1.0)"
+
+SOURCES = ["remotive", "remoteok", "jobicy", "wwr", "hn"]
+
+
+@dataclass
+class Job:
+    id: str
+    title: str
+    company: str = ""
+    url: str = ""
+    location: str = ""
+    salary: str = ""
+    category: str = ""
+    tags: List[str] = field(default_factory=list)
+    published: str = ""
+    source: str = ""
+    description: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = asdict(self)
+        # keep the public schema lean and stable
+        return {
+            "id": d["id"],
+            "title": d["title"],
+            "company": d["company"],
+            "url": d["url"],
+            "location": d["location"],
+            "salary": d["salary"],
+            "category": d["category"],
+            "tags": d["tags"],
+            "published": d["published"],
+            "source": d["source"],
+            "description": d["description"][:500],
+        }
+
+
+def _get(url: str, timeout: int = 20) -> bytes:
+    req = urllib.request.Request(url, headers={"User-Agent": UA})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        return resp.read()
+
+
+def _clean(text: str) -> str:
+    if not text:
+        return ""
+    text = re.sub(r"<[^>]+>", " ", text)
+    text = html.unescape(text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def _h(s: str) -> str:
+    return hashlib.sha1((s or "").encode("utf-8")).hexdigest()[:16]
+
+
+def fetch_remotive(limit: Optional[int] = None) -> List[Job]:
+    data = json.loads(_get("https://remotive.com/api/remote-jobs").decode("utf-8"))
+    out = []
+    for raw in data.get("jobs", []):
+        out.append(Job(
+            id=str(raw.get("id")),
+            title=_clean(raw.get("title", "")),
+            company=_clean(raw.get("company_name", "")),
+            url=raw.get("url", ""),
+            location=_clean(raw.get("candidate_required_location", "")),
+            salary=_clean(raw.get("salary", "")),
+            category=_clean(raw.get("category", "")),
+            tags=[_clean(t) for t in raw.get("tags", []) if t],
+            published=raw.get("publication_date", ""),
+            source="remotive",
+            description=_clean(raw.get("description", "")),
+        ))
+    return out[:limit] if limit else out
+
+
+def fetch_remoteok(limit: Optional[int] = None) -> List[Job]:
+    data = json.loads(_get("https://remoteok.com/api").decode("utf-8", "replace"))
+    out = []
+    for raw in data:
+        if not isinstance(raw, dict) or not raw.get("position"):
+            continue
+        lo, hi = raw.get("salary_min"), raw.get("salary_max")
+        salary = ""
+        if lo and hi:
+            salary = f"${int(lo):,}-${int(hi):,}"
+        elif lo or hi:
+            salary = f"${int(lo or hi):,}"
+        out.append(Job(
+            id=str(raw.get("id") or _h(raw.get("url", ""))),
+            title=_clean(raw.get("position", "")),
+            company=_clean(raw.get("company", "")),
+            url=raw.get("url", ""),
+            location=_clean(raw.get("location", "")),
+            salary=salary,
+            tags=[_clean(t) for t in raw.get("tags", []) if t],
+            published=raw.get("date", ""),
+            source="remoteok",
+            description=_clean(raw.get("description", "")),
+        ))
+    out = [j for j in out if j.id and j.title]
+    return out[:limit] if limit else out
+
+
+def fetch_jobicy(limit: Optional[int] = None) -> List[Job]:
+    n = limit or 50
+    data = json.loads(_get(f"https://jobicy.com/api/v2/remote-jobs?count={n}").decode("utf-8", "replace"))
+    out = []
+    for raw in data.get("jobs", []):
+        if not isinstance(raw, dict):
+            continue
+        title = _clean(raw.get("jobTitle") or "")
+        if not title:
+            continue
+        tags = []
+        for k in ("jobIndustry", "jobType"):
+            v = raw.get(k) or []
+            if isinstance(v, list):
+                tags.extend(str(t) for t in v)
+        loc = " / ".join(p for p in (raw.get("jobGeo") or "", raw.get("jobLevel") or "") if p)
+        sal = str(raw.get("salary") or "").strip()
+        if sal.upper() in ("N/A", "NA"):
+            sal = ""
+        out.append(Job(
+            id=str(raw.get("id") or _h(raw.get("url", ""))),
+            title=title,
+            company=_clean(raw.get("companyName") or ""),
+            url=raw.get("url", ""),
+            location=loc,
+            salary=sal,
+            tags=tags,
+            published=raw.get("lastUpdate") or "",
+            source="jobicy",
+            description=_clean((raw.get("jobExcerpt") or "")[:300]),
+        ))
+    out = [j for j in out if j.id and j.title]
+    return out[:limit] if limit else out
+
+
+def fetch_wwr(limit: Optional[int] = None) -> List[Job]:
+    root = ET.fromstring(_get("https://weworkremotely.com/remote-jobs.rss").decode("utf-8", "replace"))
+    out = []
+    for it in root.findall(".//item"):
+        title = (it.findtext("title") or "").strip()
+        link = (it.findtext("link") or "").strip()
+        company = ""
+        if ": " in title:
+            company, title = (p.strip() for p in title.split(": ", 1))
+        out.append(Job(
+            id=_h(link or title),
+            title=title,
+            company=company,
+            url=link,
+            category=_clean(it.findtext("category") or ""),
+            location=_clean(it.findtext("region") or ""),
+            published=(it.findtext("pubDate") or "").strip(),
+            source="wwr",
+            description=_clean(it.findtext("description") or ""),
+        ))
+    out = [j for j in out if j.id and j.title]
+    return out[:limit] if limit else out
+
+
+def fetch_hn(limit: Optional[int] = None) -> List[Job]:
+    import time
+    now = int(time.time())
+    window = now - 35 * 86400
+    res = json.loads(_get("https://hn.algolia.com/api/v1/search?%s" % urllib.parse.urlencode({
+        "query": "who is hiring", "tags": "story",
+        "numericFilters": f"created_at_i>={window}", "hitsPerPage": 20,
+    })).decode("utf-8"))
+    stories = []
+    for h in res.get("hits", []):
+        t = (h.get("title") or "").lower()
+        if "who is hiring" not in t or "analysis" in t:
+            continue
+        if "who wants to be hired" in t or "show hn" in t:
+            continue
+        stories.append(h)
+    out = []
+    for story in stories:
+        item = json.loads(_get(f"https://hn.algolia.com/api/v1/items/{story.get('objectID')}").decode("utf-8"))
+        for ch in item.get("children", [])[:100]:
+            cid = ch.get("id")
+            base = f"https://news.ycombinator.com/item?id={cid}"
+            raw = ch.get("text") or ""
+            if not raw:
+                continue
+            # split on the RAW lines first (before any whitespace collapsing),
+            # then clean each line individually.
+            for line in raw.splitlines():
+                s = _clean(line).lstrip("-*• \t").strip()
+                if not s or len(s) > 120:
+                    continue  # multi-sentence blocks are not single-job lines
+                title = company = ""
+                if "|" in s:
+                    parts = [p.strip() for p in s.split("|")]
+                    if len(parts) >= 2:
+                        company, title = parts[0], parts[1]
+                else:
+                    m = re.match(r"^([A-Z][A-Za-z0-9&.'\-]{0,60}?)\s*(?:—|–|:|-)\s+(.{3,120})$", s)
+                    if m:
+                        company, title = m.group(1), m.group(2)
+                if not title or len(title) < 3 or len(title) > 100:
+                    continue
+                if not company or company.lower() in ("http", "https", "i", "we", "a", "the"):
+                    continue
+                if "http" in title.lower():
+                    continue  # title must not be a URL
+                out.append(Job(
+                    id=_h(f"{cid}|{title}"),
+                    title=title, company=company, url=base,
+                    source="hn", description=s[:300],
+                ))
+    out = [j for j in out if j.id and j.title]
+    return out[:limit] if limit else out
+
+
+_FETCHERS = {
+    "remotive": fetch_remotive,
+    "remoteok": fetch_remoteok,
+    "jobicy": fetch_jobicy,
+    "wwr": fetch_wwr,
+    "hn": fetch_hn,
+}
+
+
+def collect(sources: Optional[List[str]] = None, limit: Optional[int] = None,
+            per_source_limit: int = 100) -> List[Job]:
+    """Fetch from the given sources (default: all), dedupe by URL, return flat list."""
+    sources = sources or SOURCES
+    seen: set = set()
+    out: List[Job] = []
+    for src in sources:
+        fn = _FETCHERS.get(src)
+        if not fn:
+            continue
+        try:
+            for j in fn(limit=per_source_limit):
+                key = j.url or j.id
+                if key in seen:
+                    continue
+                seen.add(key)
+                out.append(j)
+        except Exception:
+            # a flaky source should not break the whole API
+            continue
+    # sort: newest-ish first (published desc, fall back to source order)
+    out.sort(key=lambda j: (j.published or ""), reverse=True)
+    return out[:limit] if limit else out
+
+
+def _match_score(job: Job, skills: List[str]) -> int:
+    """Deterministic 0-100 fit score: title hits weigh more than body hits."""
+    if not skills:
+        return 50
+    title = job.title.lower()
+    hay = job.haystack if hasattr(job, "haystack") else " ".join(
+        [job.title, job.company, job.category, job.location, job.salary,
+         " ".join(job.tags), job.description]).lower()
+    score = 0.0
+    for s in skills:
+        s = s.lower().strip()
+        if not s:
+            continue
+        if s in title:
+            score += 40
+        elif s in hay:
+            score += 15
+    return int(max(0, min(100, score)))
+
+
+def filter_and_rank(jobs: List[Job], skills: Optional[List[str]] = None,
+                    remote_only: bool = False, source: Optional[str] = None,
+                    min_score: Optional[int] = None) -> List[Dict[str, Any]]:
+    out = []
+    for j in jobs:
+        if source and j.source != source:
+            continue
+        d = j.to_dict()
+        d["fit_score"] = _match_score(j, skills or [])
+        if min_score is not None and d["fit_score"] < min_score:
+            continue
+        out.append(d)
+    # best fit first, then newest
+    out.sort(key=lambda d: (d["fit_score"], d["published"]), reverse=True)
+    return out

remote_jobs_api-1.1.0/remote_jobs_api/server.py

@@ -0,0 +1,131 @@
+"""Remote-Jobs Data API — stdlib HTTP server.
+
+Endpoints:
+  GET /health                 -> {"status":"ok","sources":[...],"count_live":N}
+  GET /v1/jobs                -> normalized job listings
+  GET /v1/jobs/sources        -> {"sources":[...]}
+
+Query params on /v1/jobs:
+  skills   comma-separated keywords (e.g. "python,backend,api") -> fit_score 0-100
+  source   remotive|remoteok|jobicy|wwr|hn   (filter to one board)
+  limit    max results (default 50, max 500)
+  min_score   minimum fit_score to return (0-100)
+  format   json|csv (default json)
+
+Design: stdlib-only, no deps. Run:  python3 -m remote_jobs_api.server
+"""
+from __future__ import annotations
+
+import csv
+import io
+import json
+import os
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import urlparse, parse_qs
+
+from . import feed
+from .feed import SOURCES
+
+# In-memory cache: fetch is slow + upstreams rate-limit. Cache for N seconds.
+_CACHE_TTL = int(os.environ.get("RJA_CACHE_TTL", "300"))  # 5 min
+_cache: dict = {"ts": 0.0, "jobs": []}
+
+
+def _cached_all(force: bool = False) -> list:
+    now = time.time()
+    if not force and now - _cache["ts"] < _CACHE_TTL and _cache["jobs"]:
+        return _cache["jobs"]
+    jobs = feed.collect(per_source_limit=120)
+    _cache["ts"] = now
+    _cache["jobs"] = jobs
+    return jobs
+
+
+class Handler(BaseHTTPRequestHandler):
+    server_version = "RemoteJobsAPI/1.0"
+
+    def log_message(self, *a):  # quiet
+        pass
+
+    def _send(self, code: int, body: bytes, ctype: str = "application/json"):
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _json(self, code: int, obj):
+        self._send(code, json.dumps(obj, ensure_ascii=False).encode("utf-8"))
+
+    def do_OPTIONS(self):
+        self.send_response(204)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "*")
+        self.end_headers()
+
+    def do_GET(self):
+        parsed = urlparse(self.path)
+        path = parsed.path.rstrip("/") or "/"
+        q = parse_qs(parsed.query)
+
+        if path == "/health":
+            live = len(_cached_all())
+            return self._json(200, {"status": "ok", "sources": SOURCES, "count_live": live})
+
+        if path == "/v1/jobs/sources":
+            return self._json(200, {"sources": SOURCES})
+
+        if path == "/v1/jobs":
+            skills = [s.strip() for s in (q.get("skills", [""])[0]).split(",") if s.strip()]
+            source = (q.get("source", [""])[0] or "").strip() or None
+            if source and source not in SOURCES:
+                return self._json(400, {"error": f"unknown source {source!r}; choose from {SOURCES}"})
+            try:
+                limit = max(1, min(500, int(q.get("limit", ["50"])[0])))
+            except ValueError:
+                limit = 50
+            min_score = None
+            if q.get("min_score", [""])[0].strip():
+                try:
+                    min_score = int(q["min_score"][0])
+                except ValueError:
+                    return self._json(400, {"error": "min_score must be an int"})
+            fmt = (q.get("format", ["json"])[0] or "json").lower()
+
+            jobs = feed.filter_and_rank(
+                _cached_all(), skills=skills, source=source, min_score=min_score
+            )[:limit]
+
+            if fmt == "csv":
+                buf = io.StringIO()
+                cols = ["id", "title", "company", "location", "salary",
+                        "category", "source", "published", "fit_score", "url"]
+                w = csv.DictWriter(buf, fieldnames=cols, extrasaction="ignore")
+                w.writeheader()
+                for j in jobs:
+                    w.writerow(j)
+                return self._send(200, buf.getvalue().encode("utf-8"), "text/csv")
+
+            return self._json(200, {
+                "count": len(jobs),
+                "generated_at": int(time.time()),
+                "query": {"skills": skills, "source": source, "min_score": min_score, "limit": limit},
+                "jobs": jobs,
+            })
+
+        return self._json(404, {"error": "not found",
+                                "routes": ["/health", "/v1/jobs", "/v1/jobs/sources"]})
+
+
+def main():
+    port = int(os.environ.get("PORT", "8321"))
+    srv = ThreadingHTTPServer(("0.0.0.0", port), Handler)
+    print(f"Remote-Jobs Data API listening on :{port}", flush=True)
+    srv.serve_forever()
+
+
+if __name__ == "__main__":
+    main()

remote_jobs_api-1.1.0/remote_jobs_api.egg-info/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: remote-jobs-api
+Version: 1.1.0
+Summary: Normalized remote-job data across 5 boards — one endpoint, one schema, skill fit-score
+Author-email: Nova <earnnova@tten.no>
+License: MIT
+Project-URL: Homepage, https://github.com/earnnova-dev/remote-jobs-api
+Project-URL: Documentation, https://earnnova-dev.github.io/remote-jobs-api/
+Keywords: jobs,remote,api,scraping,feed,aggregator,data
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Remote Jobs API
+
+**Live, normalized remote-job data across 5 boards — one clean endpoint, one schema.**
+
+Stop scraping Remotive / RemoteOK / We Work Remotely / Jobicy / Hacker News
+yourself. This API pulls them, normalizes every listing into a single
+schema, dedupes, and hands you structured JSON (or CSV) — with an optional
+**0-100 skill fit-score** for ranking.
+
+Built for:
+- Job boards & aggregator sites
+- Recruiter and ATS tooling
+- Lead-gen and market research
+- **AI agents** that need structured job data in one call
+
+## Why it's different
+- **One schema, every board.** No per-board adapters on your side.
+- **No session scraping.** Reads public job-board endpoints — your data never
+  leaves their servers, no browser, no account.
+- **Self-hostable.** Stdlib-only Python (zero dependencies). Run it on a
+  laptop, a $5 VPS, or containerize it with the included Dockerfile.
+- **Deterministic fit scoring.** No hidden LLM, no black box — reproducible
+  ranking you can reason about and unit-test.
+
+## Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Status + live job count |
+| GET | `/v1/jobs/sources` | Available boards |
+| GET | `/v1/jobs` | Normalized job listings |
+
+### GET /v1/jobs
+
+Query params:
+
+| Param | Type | Notes |
+|-------|------|-------|
+| `skills` | string | Comma-separated keywords → adds `fit_score`, ranks best-first |
+| `source` | string | `remotive` / `remoteok` / `jobicy` / `wwr` / `hn` |
+| `limit` | int | 1-500 (default 50) |
+| `min_score` | int | 0-100, filter by fit (needs `skills`) |
+| `format` | string | `json` (default) or `csv` |
+
+### Example
+
+```bash
+curl "https://<your-host>/v1/jobs?skills=python,backend,api&limit=3"
+```
+
+```json
+{
+  "count": 3,
+  "generated_at": 1790433192,
+  "jobs": [
+    {
+      "id": "94516b10164d3c70",
+      "title": "Senior Backend Developer (Python)",
+      "company": "Proxify AB",
+      "url": "https://weworkremotely.com/remote-jobs/proxify-ab-senior-backend-developer-python-10",
+      "location": "Anywhere in the World",
+      "category": "Back-End Programming",
+      "source": "wwr",
+      "published": "Tue, 15 Sep 2026 09:01:36 +0000",
+      "fit_score": 80
+    }
+  ]
+}
+```
+
+## Run it yourself
+
+Zero runtime dependencies — it's pure Python stdlib.
+
+**Option A — CLI (query the feed directly, no server needed):**
+
+```bash
+pip install remote-jobs-api
+remote-jobs-api --skills python,api --limit 5
+remote-jobs-api --source wwr --format csv
+remote-jobs-api --help
+```
+
+**Option B — HTTP API server (self-host):**
+
+```bash
+pip install remote-jobs-api
+remote-jobs-api --serve --port 8321        # or: python -m remote_jobs_api.server
+```
+
+Or from source / Docker:
+
+```bash
+git clone https://github.com/earnnova-dev/remote-jobs-api
+cd remote-jobs-api
+python3 -m remote_jobs_api.server          # listens on :8321
+```
+
+```bash
+docker build -t remote-jobs-api .
+docker run -p 8321:8321 remote-jobs-api
+```
+
+Env vars:
+- `PORT` (default `8321`)
+- `RJA_CACHE_TTL` (default `300` s) — how long to cache upstream fetches
+
+## Testing
+
+Offline unit tests (no network): `python -m pytest`.
+
+## Pricing (indicative, for a hosted tier)
+
+| Plan | Price | Includes |
+|------|-------|----------|
+| **Free** | $0 | 100 calls/mo, all boards, 50 results/req |
+| **Pro** | $19/mo | 10k calls/mo, CSV, min_score, higher limits |
+| **Team** | $49/mo | 100k calls/mo, SLA, webhooks (soon) |
+
+> Self-hosted = free, MIT. The paid tier is the hosted, always-on,
+> high-rate-limit version — the same engine, managed for you.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Data & compliance
+
+This API only reads public, no-auth job-board endpoints and returns data
+exactly as those boards publish it. It does not store your personal data,
+does not scrape authenticated sessions, and does not resell any board's
+proprietary content beyond what is publicly viewable.

remote_jobs_api-1.1.0/remote_jobs_api.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+remote_jobs_api/__init__.py
+remote_jobs_api/__main__.py
+remote_jobs_api/cli.py
+remote_jobs_api/feed.py
+remote_jobs_api/server.py
+remote_jobs_api.egg-info/PKG-INFO
+remote_jobs_api.egg-info/SOURCES.txt
+remote_jobs_api.egg-info/dependency_links.txt
+remote_jobs_api.egg-info/entry_points.txt
+remote_jobs_api.egg-info/top_level.txt
+tests/test_feed.py

remote_jobs_api-1.1.0/remote_jobs_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

remote_jobs_api-1.1.0/remote_jobs_api.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+remote-jobs-api = remote_jobs_api.cli:main

remote_jobs_api-1.1.0/remote_jobs_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+remote_jobs_api

remote_jobs_api-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

remote_jobs_api-1.1.0/tests/test_feed.py

@@ -0,0 +1,161 @@
+"""Offline unit tests — no network.
+
+Covers the normalization helpers, the fit-score, filter_and_rank, and the
+CLI argument parsing, using in-memory fixtures.
+"""
+from __future__ import annotations
+
+import io
+import json
+import sys
+from contextlib import redirect_stdout
+
+import pytest
+
+from remote_jobs_api import feed
+from remote_jobs_api.feed import Job, _clean, _h, _match_score, filter_and_rank, SOURCES
+
+
+# --- helpers -------------------------------------------------------------
+
+def _job(**kw) -> Job:
+    base = dict(id="x", title="Senior Backend Developer", company="Acme",
+                url="https://example.com/j/x", source="test")
+    base.update(kw)
+    return Job(**base)
+
+
+# --- _clean --------------------------------------------------------------
+
+def test_clean_strips_tags_and_whitespace():
+    assert _clean("<b>  Hello </b>\n  World ") == "Hello World"
+
+
+def test_clean_unescapes_entities():
+    assert _clean("A &amp; B") == "A & B"
+
+
+def test_clean_empty():
+    assert _clean("") == ""
+    assert _clean(None) == ""
+
+
+# --- _h deterministic hash -----------------------------------------------
+
+def test_hash_stable_and_short():
+    a = _h("hello")
+    b = _h("hello")
+    assert a == b
+    assert len(a) == 16
+
+
+def test_hash_differs():
+    assert _h("a") != _h("b")
+
+
+# --- Job.to_dict lean schema --------------------------------------------
+
+def test_to_dict_has_core_fields():
+    d = _job().to_dict()
+    for k in ("id", "title", "company", "url", "location", "salary",
+              "category", "tags", "published", "source"):
+        assert k in d
+
+
+def test_to_dict_truncates_description():
+    d = _job(description="x" * 2000).to_dict()
+    assert len(d["description"]) <= 500
+
+
+# --- _match_score --------------------------------------------------------
+
+def test_score_title_hit_higher_than_body():
+    title_hit = _job(title="Python Backend", description="")
+    body_hit = _job(title="Designer", description="we use python a lot")
+    assert _match_score(title_hit, ["python"]) > _match_score(body_hit, ["python"])
+
+
+def test_score_bounds():
+    assert _match_score(_job(), []) == 50
+    assert 0 <= _match_score(_job(title="Python Python Python"), ["python"]) <= 100
+
+
+def test_score_case_insensitive():
+    assert _match_score(_job(title="PYTHON"), ["python"]) >= 40
+
+
+# --- filter_and_rank -----------------------------------------------------
+
+def test_filter_source():
+    a = _job(id="a", source="remotive")
+    b = _job(id="b", source="wwr")
+    out = filter_and_rank([a, b], source="wwr")
+    assert [d["id"] for d in out] == ["b"]
+
+
+def test_filter_min_score():
+    high = _job(id="high", title="Python Senior")
+    low = _job(id="low", title="Designer")
+    out = filter_and_rank([high, low], skills=["python"], min_score=40)
+    assert all(d["fit_score"] >= 40 for d in out)
+
+
+def test_rank_best_fit_first():
+    # A job matching TWO distinct skills outranks one matching only one.
+    # (Repeating a single skill does not raise the score — each skill counts once.)
+    a = _job(id="a", title="Python Developer")
+    b = _job(id="b", title="Senior Python Engineer", tags=["api"])
+    out = filter_and_rank([a, b], skills=["python", "api"])
+    assert out[0]["id"] == "b"
+    assert out[0]["fit_score"] > out[1]["fit_score"]
+
+
+# --- sources registry ----------------------------------------------------
+
+def test_sources_known():
+    assert set(SOURCES) == {"remotive", "remoteok", "jobicy", "wwr", "hn"}
+
+
+# --- CLI -----------------------------------------------------------------
+
+def _run_cli(argv):
+    from remote_jobs_api import cli
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        # monkeypatch collect so the CLI stays offline
+        orig = feed.collect
+        feed.collect = lambda *a, **k: [
+            _job(id="a", title="Python Backend", source="remotive"),
+            _job(id="b", title="Growth Designer", source="wwr"),
+        ]
+        try:
+            rc = cli.main(argv)
+        finally:
+            feed.collect = orig
+    return rc, buf.getvalue()
+
+
+def test_cli_json_output():
+    rc, out = _run_cli(["--skills", "python", "--limit", "5"])
+    assert rc == 0
+    data = json.loads(out)
+    assert data["count"] == 2
+    assert data["jobs"][0]["fit_score"] >= 40
+
+
+def test_cli_source_filter():
+    rc, out = _run_cli(["--source", "wwr"])
+    data = json.loads(out)
+    assert all(j["source"] == "wwr" for j in data["jobs"])
+
+
+def test_cli_csv_output():
+    rc, out = _run_cli(["--format", "csv"])
+    assert rc == 0
+    lines = out.strip().splitlines()
+    assert lines[0].startswith("id,")
+    assert len(lines) == 3  # header + 2 rows
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main([__file__, "-v"]))