# Moving from Fantastic.jobs

Their `_advanced` boolean expressions work here as written, and their parameter names are accepted as aliases. This page lists every difference, side by side.

**What this covers:** What you change, and what you do not; The parameter map; Their documented examples, side by side; Where the grammars differ.

**Assumed knowledge:** That you have a working Fantastic.jobs integration and a JOA API key.

**Canonical HTML:** https://jobopportunitiesapi.org/docs/moving-from-fantastic-jobs  
**Machine-readable index:** https://jobopportunitiesapi.org/docs/ai/index.md  
**Last verified:** 2026-11-10  
**Superseded by:** the live API at https://api.jobopportunitiesapi.org and its spec at https://jobopportunitiesapi.org/openapi.json. Where this file and the API disagree, the API is right.

---

<a id="fj-what-changes"></a>

## 1. What you change, and what you do not

Change the host, the path and the key. Keep the boolean expressions: `(react | vue) & (node | golang) & !aws` means the same thing on both APIs.

### 1.1 In depth

- **Host and path.** Their job routes are `/v1/active-ats`, `/v1/active-jb` and the `expired-` and `modified-` variants. Ours is one route, `GET https://api.jobopportunitiesapi.org/v1/jobs`, for every source, with `GET /v1/jobs/closed` for postings that came off their source and `GET /v1/changes` for the delta feed.
- **Key.** `Authorization: Bearer <key>`. See [authentication](./api-authentication.md).
- **Boolean notation.** `&` `|` `!` `:*` `<->` `<N>`, single-quoted phrases and parentheses are part of our grammar, with the same precedence (`!` before `&` before `|`). The full grammar: [the query grammar](./api-filtering.md#query-grammar).
- **Parameter names.** `title_advanced`, `description_advanced` and `organization_advanced` are accepted as aliases (the table below). `location_advanced` is not: places are structured filters here.

<a id="fj-parameter-map"></a>

## 2. The parameter map

Each Fantastic.jobs name, the JOA parameter it maps to, and the difference if there is one.

### 2.1 In depth

| Fantastic.jobs | JOA | Difference |
| --- | --- | --- |
| `title_advanced` (also `advanced_title_filter`, `title_filter`) | `title` | None in meaning: a boolean search of the job title. |
| `title` | `title` | Their bare `title` is Google-style (space is AND, quotes, leading `-`). Ours takes the same and the full grammar. |
| `description_advanced` (also `advanced_description_filter`, `description_filter`) | `description_contains` | Theirs searches the title and the description as one text. Ours searches the advert text only, and live postings only. Adverts almost always repeat the title, but a term that is only in the title is not matched: add `title=` for that. |
| `description` | `q` or `description_contains` | Not an alias, because it is ambiguous here: `q` searches title, company and location; `description_contains` the advert text. |
| `organization_advanced` (also `advanced_organization_filter`) | `company_name_contains` | None in meaning: a boolean search of the employer name. |
| `organization`, `exclude_organization` | `company_name_contains` or `company` | Refused with a 400 naming the JOA parameter. Exclude with `company_name_contains=!(Amazon \| Meta)`. |
| `location_advanced`, `location` | `country`, `city`, `state`, `region` | `location_advanced` is refused with a 400 naming these. Our places are normalised fields (ISO country codes), not a text to search: a country name is present in the location text of a minority of the rows of that country, so a text search would silently miss most of them. |
| `date_posted_gte`, `date_posted_lt` | `posted_after`, `posted_before` | Not aliases. `listed_after` is the time a row reached the API, the one to poll on. |
| `limit`, `offset` | `limit`, `cursor` | `limit` is 1 to 200. Paging is keyset: follow `next_via`; `offset` is refused. |

> **An alias and its JOA name together**: Fantastic.jobs lets `title_advanced` win silently when `title` is also sent. Here the two together with different values are a 400 `conflicting_parameters`, because one of them would be ignored without a word. Send one.

<a id="fj-side-by-side"></a>

## 3. Their documented examples, side by side

Every example from the Fantastic.jobs advanced searching guide, and the JOA request that answers it.

### 3.1 In depth

_The alias names work too: title_advanced=... is the same request as title=...._
| Fantastic.jobs | JOA |
| --- | --- |
| `title_advanced=(AI \| 'machine learning' \| robotics) & !marketing` | `title=(AI \| 'machine learning' \| robotics) & !marketing` |
| `title_advanced=senior & (python \| rust) & !staff` | `title=senior & (python \| rust) & !staff` |
| `title_advanced=project <-> manag:*` | `title=project <-> manag:*` |
| `title_advanced='data engineer' \| 'data scientist' \| 'analytics engineer'` | `title='data engineer' \| 'data scientist' \| 'analytics engineer'` |
| `description_advanced='remote work' & (equity \| 'stock options') & !contractor` | `description_contains='remote work' & (equity \| 'stock options') & !contractor` |
| `description_advanced=(kubernetes \| k8s) & terraform & aws` | `description_contains=(kubernetes \| k8s) & terraform & aws` |
| `location_advanced='United States' & !California` | `country=US`, then drop rows with `state` CA on your side, or list the states you want in `state=` |
| `location_advanced=Germany & !(Berlin \| Munich)` | `country=DE`, then drop the two cities on your side, or list the cities you want in `city=` |
| `location_advanced='New York' \| 'San Francisco' \| Boston` | `city=New York,San Francisco,Boston` |
| `organization_advanced=University & !Harvard` | `company_name_contains=University & !Harvard` |
| `organization_advanced=(Microsoft \| Google \| Apple)` | `company_name_contains=(Microsoft \| Google \| Apple)` |
| `organization_advanced=OpenAI \| 'Open AI'` | `company_name_contains=OpenAI \| 'Open AI'` |

Their combined example, on JOA

```bash
curl -s -H "Authorization: Bearer $JOA_KEY" --get \
  https://api.jobopportunitiesapi.org/v1/jobs \
  --data-urlencode 'title=(engineer | developer) & !manager' \
  --data-urlencode 'country=US' \
  --data-urlencode 'company_name_contains=!(Amazon | Meta | Google)' \
  --data-urlencode "description_contains=remote & (equity | 'stock options')" \
  --data-urlencode 'limit=5'
```

<a id="fj-grammar-differences"></a>

## 4. Where the grammars differ

Ours accepts everything theirs does, plus a few forms theirs refuses. Errors are 422 here, 400 there.

### 4.1 In depth

- **A space is AND here.** `title_advanced=software engineer` is a 400 on Fantastic.jobs, which requires an explicit operator between terms. Here it is `software & engineer`.
- **Word operators too.** `AND`, `OR` and `NOT` (upper case) work as well as `&` `|` `!`, and `-word` excludes. Quote `"OR"` to search for the word.
- **Prefix.** `manag:*` and `manag*` are the same. A prefix needs 3 or more characters. A bare word is always exact, as on Fantastic.jobs.
- **Phrases.** `'machine learning'` and `"machine learning"` are both the words adjacent and in order.
- **Errors.** A malformed expression is a **422** `query_syntax` (Fantastic.jobs answers 400), and the message names the character position. A boolean expression of more than 32 terms or parentheses nested more than 8 deep is a **422** `query_too_complex`. Values may be up to 500 bytes. A refused request costs no records.
- **Matching.** Case-insensitive and accent-insensitive. `OpenAI` and `Open AI` are different words here too: list both.

**See also**

- [The query grammar: phrases, AND, OR, NOT, prefix and parentheses](./api-filtering.md#query-grammar)

---

## Where to go next

This file is part of **Start here**. Others in the same group:

- [Overview](./overview.md): What the Job Opportunities API is, what it deliberately is not, and the ten minutes of reading that will save you the most time.
- [Quickstart](./quickstart.md): From nothing to a real response in one command, and to an authenticated one in about a minute. No card at any point.
- [If you are a program](./for-agents.md): This documentation has a plain-Markdown mirror with no JavaScript, no redirects and no browser required. Here is where it is and what is in it.
- [MCP server](./mcp.md): A remote MCP server at api.jobopportunitiesapi.org/mcp (Streamable HTTP), so an AI agent in Claude, Cursor, Windsurf, VS Code or Cline can search live job postings with the same key, metering and plan limits as the REST API.
- [How to read this site](./conventions.md): Three tiers on every concept, a copyable link on every section, and a rule about numbers that explains why almost nothing here is typed by hand.

Always useful:

- [index.md](./index.md): the map of every file here
- [BUILD-A-SITE.md](./BUILD-A-SITE.md): the paste-whole brief for building against this API
- [quickstart.md](./quickstart.md): zero to a first authenticated response
- [api-errors.md](./api-errors.md): every status code and whether to retry it
