# páGinasamarelas — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for Portuguese businesses by name or category, browse Yellow Pages listings, and access detailed company information like contact details, addresses, and services. Find the right local business quickly with filters and comprehensive business profiles from Portugal's official business directory.

**Category:** Business Directories | **Website:** [xn--pginasamarelas-vgb.pt/](https://xn--pginasamarelas-vgb.pt/) | **Docs:** [parse.bot/marketplace/49ebedd5-1771-48d8-a091-658e8795f0ab/p-ginasamarelas-pt-api](https://parse.bot/marketplace/49ebedd5-1771-48d8-a091-658e8795f0ab/p-ginasamarelas-pt-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/paginasamarelas/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Browse category

Browse businesses or sub-categories within a category slug. Top-level categories (e.g., 'comer-beber') return sub_categories; leaf categories (e.g., 'restaurantes') return businesses. Supports pagination and optional location filtering. Slugs are obtained from list_categories or from the sub_categories in a parent browse_category response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `location` | string | No | Optional location filter (e.g., 'Porto'). Omitting returns results across all locations. |
| `page` | integer | No | Page number for pagination. |
| `slug` | string | Yes | Category slug from list_categories or browse_category results (e.g., 'comer-beber', 'restaurantes'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/paginasamarelas/browse-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"location":"<string>","page":"<integer>","slug":"<string>"}'
```

### Get business by id

Retrieve full details for a business using its numeric ID. Returns the same fields as get_business_detail. The ID is available from search_businesses results. Internally resolves to the business detail page.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Numeric ID of the business (e.g., '4132'). Available from search_businesses results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/paginasamarelas/get-business-by-id \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"id":"<string>"}'
```

### Get business detail

Retrieve full details for a single business using its detail page URL. Returns contact information (phone, website), opening hours by day, categories/tags, geo coordinates, description, logo, and image. The URL is typically obtained from search_businesses or browse_category results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | string | Yes | Full URL of the business detail page (e.g., 'https://www.pai.pt/paginas/4132-restaurante-bar-caldeiras-vulcoes'). Available from search_businesses results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/paginasamarelas/get-business-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"<string>"}'
```

### List categories

List top-level categories from the pai.pt homepage. Returns category names, URL slugs, full URLs, and approximate result counts. These slugs are used as input to browse_category.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/paginasamarelas/list-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Search businesses

Full-text search over the pai.pt business directory. query matches business names and categories; location narrows geographically. Returns paginated results with business summaries including name, URL, ID, slug, category, and address. Pagination via page parameter. total_results reflects the server's count for the query/location combination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `location` | string | No | Location filter (e.g., 'Lisboa', 'Porto'). Omitting returns results across all of Portugal. |
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search keyword (e.g., 'restaurante', 'hotel', 'dentista'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/paginasamarelas/search-businesses \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"location":"<string>","page":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.