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

> ## Agent Instructions
> Perceptlayer is a web data API: one key for structured JSON from about 250 websites. Base URL https://api.perceptlayer.com.
> Send the key in the X-API-Key header. GET parameters go in the query string; POST parameters in a JSON body.
> A successful call costs the credits on its endpoint (X-Credits-Used); failed calls cost nothing. Errors are {"error": {"code", "message", "request_id"}}.
> AI agents can use every endpoint through the MCP server at https://api.perceptlayer.com/mcp (tools search_endpoints, get_endpoint, call_endpoint), with Authorization: Bearer <key>.
> Get a free key at https://perceptlayer.com/signup.

# Quick start

> Create an API key and make your first call.

**1. Create an account**

[Sign up](https://perceptlayer.com/signup) with your email and open the link we send you. The link works once and expires after 15 minutes.

New accounts get 1,000 free credits once they verify their email, topped back up each month until the first purchase. The free rate is 1 request a second (60 a minute).

**2. Create a key**

In the [dashboard](https://perceptlayer.com/dashboard/keys), create a key. It starts with `sk_live_` and is shown once, so store it somewhere safe.

```bash theme={"dark"}
export API_KEY="sk_live_..."
```

**3. Make a call**

Search Google Maps for restaurants in New York:

```bash cURL theme={"dark"}
curl "https://api.perceptlayer.com/v1/google-maps/simple-search?query=restaurants+in+new+york" \
  -H "X-API-Key: $API_KEY"
```

```python Python theme={"dark"}
import os
import requests

response = requests.get(
    "https://api.perceptlayer.com/v1/google-maps/simple-search",
    params={"query": "restaurants in new york"},
    headers={"X-API-Key": os.environ["API_KEY"]},
    timeout=60,
)
response.raise_for_status()
print(response.headers["X-Credits-Used"], response.json())
```

```javascript Node.js theme={"dark"}
const url = new URL("https://api.perceptlayer.com/v1/google-maps/simple-search");
url.searchParams.set("query", "restaurants in new york");

const response = await fetch(url, {
  headers: { "X-API-Key": process.env.API_KEY },
  signal: AbortSignal.timeout(60_000),
});
if (!response.ok) throw new Error((await response.json()).error.message);
console.log(response.headers.get("X-Credits-Used"), await response.json());
```

**4. Read the response**

The body is the data itself:

```json theme={"dark"}
{
  "items": [
    {
      "name": "Altair Restaurant NYC",
      "review_count": 1225,
      "rating": 4.8,
      "website": "https://www.altairnyc.com/",
      "full_address": "351 W 38th St, New York, NY 10018, United States"
    }
  ]
}
```

Shortened from a recorded response. The `X-Credits-Used` header says what the call cost, and `X-Credits-Remaining` shows your balance.

## Next steps

> **[Find an endpoint](https://docs.perceptlayer.com/api-reference/introduction.md)**
>
> Every source and endpoint, with a playground.

> **[Connect an agent](https://docs.perceptlayer.com/ai-agents.md)**
>
> Use the catalogue from Claude Code, Cursor or VS Code.


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