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

# Location and headers

> Read a page from another country, ask the site for a language, send your own request headers, and read a page with an expired certificate.

`location` reads a page from another country and asks the site for the languages you want. `headers` sends your own request headers to the site. These fields change what the site shows you, so a read that uses `headers`, `location.languages` or `skipTlsVerification` is always live.

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). This request reads a page that echoes the headers it received, from Germany, in German, with one custom header.

```bash cURL 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://httpbin.org/headers",
    "location": { "country": "DE", "languages": ["de-DE", "en"] },
    "headers": { "x-plan": "pro" }
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/scrape", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://httpbin.org/headers",
    location: { country: "DE", languages: ["de-DE", "en"] },
    headers: { "x-plan": "pro" },
  }),
});
const { data } = await response.json();
console.log(data.markdown);
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/scrape",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "url": "https://httpbin.org/headers",
        "location": {"country": "DE", "languages": ["de-DE", "en"]},
        "headers": {"x-plan": "pro"},
    },
)
print(response.json()["data"]["markdown"])
```

## Read the response

The page lists the headers it got. Two of them are the ones you sent: the languages, best first, and your `x-plan` header. This real response is cut to those two headers.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "{\n  \"headers\": {\n    \"Accept-Language\": \"de-DE,en;q=0.9\",\n    …\n    \"X-Plan\": \"pro\"\n  }\n}",
    "metadata": {
      "sourceURL": "https://httpbin.org/headers",
      "url": "https://httpbin.org/headers",
      "statusCode": 200,
      "contentType": "application/json",
      "cacheState": "miss",
      "scrapeId": "b519c656-9983-485b-a247-8e4449e16208",
      "costUsd": 0.001
    }
  },
  "id": "b519c656-9983-485b-a247-8e4449e16208",
  "costUsd": 0.001,
  "requestId": "b519c656-9983-485b-a247-8e4449e16208"
}
```

## Options

| Field | Type | Default | Effect |
| - | - | - | - |
| `location.country` | `string` | `"US"` | A two-letter country code such as `DE` or `JP`, in any case. `UK` is read as `GB`. The read starts from that country. |
| `location.languages` | `array of string` | none | 1 to 5 languages to ask the site for, best first, such as `["de", "en"]` or `["pt-BR"]`. Sent as `Accept-Language`. |
| `headers` | `object` | none | Extra request headers to send to the site, such as `{ "x-plan": "pro" }`. |
| `skipTlsVerification` | `boolean` | `false` | Read a page whose certificate is expired, self-signed or for another name. The read is not private against someone between Stophy and the site. |
| `proxy` | `string` | `"auto"` | How hard a read tries. `basic` makes one plain attempt. `enhanced` starts with the stronger read, and `stealth` means the same. `auto` starts plain and tries the stronger read once if the site refuses. Same price for each. |

## Headers

* Send at most 30 headers.
* A name uses letters, digits and `-`, up to 64 characters. A value is up to 2,000 printable characters with no line breaks.
* `Host`, `Content-Length`, `Connection`, `Transfer-Encoding`, `Upgrade`, `TE` and `Proxy-Authorization` are refused, because Stophy sets them itself.
* Your Stophy API key belongs in the `Authorization` header of your request to Stophy, not in `headers`.
* Send `Cookie` or `Authorization` only for a site you are allowed to read as that user.

## Limits and errors

* A country that is not a two-letter code returns `400 invalidRequest` with the message `country: Expected a two-letter country code such as DE`.
* The country is a request. A site can still show the same page to everyone.
* A read with `headers`, `location.languages` or `skipTlsVerification` is never answered from a stored copy and never saved as one. See [Freshness and caching](https://docs.stophy.dev/scrape/freshness-and-caching.md).
* A refused header returns `400 invalidRequest` with the message `Stophy sets this header itself.`

## Price

\$1 per 1,000 pages. A country, languages, headers and `skipTlsVerification` add nothing.

## Related

* [Waiting and rendering](https://docs.stophy.dev/scrape/waiting-and-rendering.md) reads a page as a phone would.
* [Browser actions](https://docs.stophy.dev/scrape/browser-actions.md) work with the same location.
* [Freshness and caching](https://docs.stophy.dev/scrape/freshness-and-caching.md) explains when a stored copy is used.
* [Scrape overview](https://docs.stophy.dev/scrape/overview) lists every format and option.


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