> ## 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.

# Map

> List the URLs of a website without reading its pages, ranked by a topic when you send one, so you can choose which pages to read next.

Map lists a site's URLs without reading the pages, so you can choose which to read.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/map \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://bun.com",
    "search": "sqlite",
    "limit": 5
  }'
```

```typescript TypeScript theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy();

const { links } = await stophy.map({
  url: "https://bun.com",
  search: "sqlite",
  limit: 5,
});
console.log(links.map((link) => link.url));
```

```python Python theme={null}
from stophy import Stophy

stophy = Stophy()

result = stophy.map(url="https://bun.com", search="sqlite", limit=5)
print([link["url"] for link in result["links"]])
```

You get at most 5,000 URLs, subdomains included. Set `limit` from 1 to 100,000. Calls without a key list one host and have lower limits, see [Without a key](https://docs.stophy.dev/production/rate-limits.md#without-a-key).

```json theme={null}
{
  "success": true,
  "links": [
    { "url": "https://bun.com/reference/node/sqlite/constants/SQLITE_ANALYZE" },
    { "url": "https://bun.com/reference/node/sqlite/constants/SQLITE_ATTACH" }
  ]
}
```

The URLs are in `links`, best `search` match first. A row can also have `title` and `description`. A map lists what it finds in the time allowed, so it can miss pages.

## Fields

| Field | Default | What it does |
| - | - | - |
| `search` | none | Keep only URLs whose address, title or description has these words. |
| `sitemap` | `include` | `include` uses sitemaps and links, `only` lists what the sitemaps name, `skip` ignores them. |
| `includeSubdomains` | `true` | `false` lists only the host you sent. |
| `ignoreQueryParameters` | `true` | `false` keeps the `?query` part of each URL. |
| `timeout` | none | Stop after this many milliseconds, at least 1,000, and return what was found. |
| `location` | United States | `country` and `languages` to read the site from. |
| `ignoreCache` | `false` | `true` builds the list again instead of reusing one from the last 6 hours. |

## Errors

| Code | Cause | Fix |
| - | - | - |
| `503 sourceUnavailable` | The site, or its sitemap with `sitemap: "only"`, cannot be reached | Wait `retryAfterSeconds`, then retry |
| `404 notFound` | `sitemap: "only"` on a site with no sitemap | Send `sitemap: "include"` |
| `403 siteNotRead` | Stophy does not read this site | Use a [parser](https://docs.stophy.dev/scrape/prebuilt-parsers) |
| `400 invalidRequest` | A private network URL | Send a public URL |

Every other code is in [Errors](https://docs.stophy.dev/api-reference/errors.md).

## Next

* [Scrape](https://docs.stophy.dev/scrape/overview): read one of the URLs.
* [Batches](https://docs.stophy.dev/batches/overview): read a list of them.
* [Crawl](https://docs.stophy.dev/crawl/overview): read pages as links are found.


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