> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Parsers

> Read a site's own data as JSON: send its page to scrape and name one of 103 parsers, like reddit-search, youtube-transcript or google-maps.

A parser reads one kind of page on one site and returns the site's own data as JSON. A Reddit search page comes back as posts, a YouTube video link as its transcript, a Google Maps search as places. There are 103 parsers.

## Call a parser

Send the page's URL to [scrape](https://docs.stophy.dev/api-reference/endpoint/scrape.md) with a `json` format that names the parser. Parser options go in `options`.

```bash theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.youtube.com/watch?v=dQw4w9WgXcQ","formats":[{"type":"json","parser":"youtube-transcript","options":{"language":"en"}}]}'
```

> [accordion] Response
>
> This real response is cut.
>
> ```json theme={null}
> {
>   "success": true,
>   "data": {
>     "json": {
>       "videoId": "dQw4w9WgXcQ",
>       "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
>       "language": "en",
>       "isAutoGenerated": false,
>       "durationSeconds": 213,
>       "text": "[♪♪♪] ♪ We're no strangers to love ♪ ♪ You know the rules and so do I ♪ …"
>     },
>     "metadata": {
>       "sourceURL": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
>       "statusCode": 200,
>       "contentType": "application/json",
>       "scrapeId": "a506455f-08f7-4a72-abee-ddffcd984fef",
>       "creditsUsed": 1
>     }
>   }
> }
> ```

The parser's data is in `data.json`. The URL must be the kind of page the parser reads, or the call fails with `invalidRequest`.

## Find a parser

The parser pages list every parser by topic, with the page it reads, its options, what it returns, its price and a real response:

> [card] [Search and the web](https://docs.stophy.dev/sources/web.md)

> [card] [Video](https://docs.stophy.dev/sources/video.md)

> [card] [Social](https://docs.stophy.dev/sources/social.md)

> [card] [Places and travel](https://docs.stophy.dev/sources/places-and-travel.md)

> [card] [Jobs](https://docs.stophy.dev/sources/jobs.md)

> [card] [Shopping](https://docs.stophy.dev/sources/shopping.md)

> [card] [Apps](https://docs.stophy.dev/sources/apps.md)

> [card] [Real estate](https://docs.stophy.dev/sources/real-estate.md)

> [card] [Ads](https://docs.stophy.dev/sources/ads.md)

Your code or your agent can read the same list from [`GET /v1/parsers`](https://docs.stophy.dev/api-reference/endpoint/list-parsers). It is free and needs no key.

```bash theme={null}
curl -s https://api.stophy.dev/v1/parsers \
  | jq -r '.data.parsers[] | select(.name | startswith("youtube")) | "\(.name): \(.takes)"'
```

```text theme={null}
youtube-search: A YouTube search results page with the search in search_query
youtube-video: A YouTube video link: watch, youtu.be, shorts or live
youtube-transcript: A YouTube video link: watch, youtu.be, shorts or live
youtube-comments: A YouTube video link: watch, youtu.be, shorts or live
youtube-channel: A YouTube channel link: @handle, /channel/, /c/ or /user/, with an optional tab
youtube-post: A YouTube community post link: /post/Ugkx... or a community page with ?lb=
youtube-playlist: A YouTube playlist page with list in the link
```

Each entry has `takes` (the page it reads), an `example` URL, its `options`, the fields it `returns`, its `price`, `keyless: true` when it works without a key, and a sample `response`. Some parsers read more than one kind of page and list each one in `views`. Set `options.view` to pick one where `takes` says so.

## Price and keys

Each parser has its own price in credits, most of them 1 credit a call. The parsers marked `keyless: true` work without a key, within the [free limits](https://docs.stophy.dev/rate-limits.md). Paging through a parser's results needs a key. See [Page through results](https://docs.stophy.dev/guides/paging.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.