# Yellow Pages API

> Yellow Pages returns US business listings and contact details as a workflow and API.

Yellow Pages, also called YP or YellowPages.com, finds US businesses by name or category and city, state, or ZIP. Search businesses needs a business name or type and a US location; results include listings in Yellow Pages order, without labeled ads.

- Page: https://fous.com/tools/yellow-pages
- Handle: `@yellow-pages`
- Category: [Maps](https://fous.com/tools/category/maps)
- Source website: https://yellowpages.com
- Last verified: Sep 29, 2026

## Methods

### Search businesses

Operation `search_businesses`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Find local US businesses by name or category and city, state, or ZIP. Returns listings with phone numbers in Yellow Pages order, excluding labeled ads; contact details and hours appear when listed.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `sort` | string | no | `"best_match"` | Result order, for example distance. |
| `what` | string | yes | `"electrician"` | Business type or name, for example electrician. |
| `where` | string | yes | `"Dallas, TX"` | US city and state or ZIP, for example Dallas, TX or 10001. |
| `max_results` | integer | no | `30` | Maximum number of businesses, for example 30. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "what",
    "where"
  ],
  "properties": {
    "sort": {
      "enum": [
        "best_match",
        "distance",
        "average_rating",
        "name"
      ],
      "type": "string",
      "default": "best_match",
      "description": "Result order, for example distance.",
      "examples": [
        "best_match",
        "name"
      ]
    },
    "what": {
      "type": "string",
      "description": "Business type or name, for example electrician.",
      "examples": [
        "electrician",
        "coffee",
        "zzzxxyyplumbingnonexistent900"
      ]
    },
    "where": {
      "type": "string",
      "description": "US city and state or ZIP, for example Dallas, TX or 10001.",
      "examples": [
        "Dallas, TX",
        "10001"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 30,
      "maximum": 90,
      "minimum": 1,
      "description": "Maximum number of businesses, for example 30.",
      "x-fous-developer": true,
      "examples": [
        30,
        35
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "sort": "best_match",
      "what": "electrician",
      "where": "Dallas, TX",
      "max_results": 30
    },
    {
      "sort": "name",
      "what": "coffee",
      "where": "10001",
      "max_results": 35
    },
    {
      "sort": "best_match",
      "what": "zzzxxyyplumbingnonexistent900",
      "where": "Dallas, TX",
      "max_results": 30
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `businesses` | array |  | Businesses in search result order without ads. |
| `businesses[].zip` | string or null | `"75235"` | ZIP code when listed. |
| `businesses[].city` | string or null | `"Dallas"` | City when listed. |
| `businesses[].name` | string | `"Hawes Electric"` | Business name. |
| `businesses[].state` | string or null | `"TX"` | State abbreviation when listed. |
| `businesses[].rating` | number or null | `4.5` | Displayed rating out of 5, when shown. |
| `businesses[].website` | string or null | `"https://www.haweselectric.com"` | Business website when shown. |
| `businesses[].categories` | array |  | Listed business categories. |
| `businesses[].phone_number` | string | `"(214) 414-7800"` | Listed business phone number. |
| `businesses[].review_count` | integer or null | `7` | Displayed number of reviews, when shown. |
| `businesses[].street_address` | string or null | `"2138 Burbank Street"` | Street address when listed. |
| `businesses[].years_in_business` | integer or null | `81` | Years in business when shown. |
| `businesses[].yellow_pages_link` | string | `"https://www.yellowpages.com/dallas-tx/mip/hawes-electric-524808101?lid=1002194063867"` | Yellow Pages listing link. |
| `businesses[].opening_hours_or_status` | string or null | `"closed now"` | Opening hours or current open status when shown. |

**Example input**

```json
{
  "sort": "best_match",
  "what": "electrician",
  "where": "Dallas, TX",
  "max_results": 30
}
```

**Example output**

```json
{
  "businesses": [
    {
      "zip": "75235",
      "city": "Dallas",
      "name": "Hawes Electric",
      "state": "TX",
      "rating": 4.5,
      "website": "https://www.haweselectric.com",
      "categories": [
        "Electricians",
        "Lawn & Garden Equipment & Supplies",
        "Building Contractors"
      ],
      "phone_number": "(214) 414-7800",
      "review_count": 7,
      "street_address": "2138 Burbank Street",
      "years_in_business": 81,
      "yellow_pages_link": "https://www.yellowpages.com/dallas-tx/mip/hawes-electric-524808101?lid=1002194063867",
      "opening_hours_or_status": "closed now"
    },
    {
      "zip": "75081",
      "city": "Richardson",
      "name": "Richardson Ready Electric Inc",
      "state": "TX",
      "rating": 5,
      "website": "http://richardsonreadyelectricinctexas.localsearch.com",
      "categories": [
        "Electricians"
      ],
      "phone_number": "(972) 362-4784",
      "review_count": 1,
      "street_address": "620 N Interurban St",
      "years_in_business": 38,
      "yellow_pages_link": "https://www.yellowpages.com/richardson-tx/mip/richardson-ready-electric-inc-3711837?lid=1002195553656",
      "opening_hours_or_status": "closed now"
    },
    {
      "zip": "76092",
      "city": "Southlake",
      "name": "Berkeys Air Conditioning, Plumbing & Electrical",
      "state": "TX",
      "rating": 5,
      "website": "http://www.berkeys.com/",
      "categories": [
        "Electricians",
        "Air Conditioning Contractors & Systems",
        "Air Duct Cleaning"
      ],
      "phone_number": "(972) 460-6860",
      "review_count": 93,
      "street_address": "1070 South Kimball Avenue",
      "years_in_business": 51,
      "yellow_pages_link": "https://www.yellowpages.com/southlake-tx/mip/berkeys-air-conditioning-plumbing-electrical-478332101?lid=1002192971817",
      "opening_hours_or_status": "closing soon"
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@yellow-pages",
  "visibility": "public",
  "operation": "search_businesses",
  "version": 1,
  "input": {
    "sort": "best_match",
    "what": "electrician",
    "where": "Dallas, TX",
    "max_results": 30
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@yellow-pages\",\n  \"visibility\": \"public\",\n  \"operation\": \"search_businesses\",\n  \"version\": 1,\n  \"input\": {\n    \"sort\": \"best_match\",\n    \"what\": \"electrician\",\n    \"where\": \"Dallas, TX\",\n    \"max_results\": 30\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@yellow-pages",
  "visibility": "public",
  "operation": "search_businesses",
  "version": 1,
  "input": {
    "sort": "best_match",
    "what": "electrician",
    "where": "Dallas, TX",
    "max_results": 30
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/yellow-pages`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `search_businesses`: Search businesses. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-yellow-pages https://api.fous.com/mcp/tools/yellow-pages --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Find electricians in a city or ZIP code
- Gather local business phone numbers
- Compare listed ratings and review counts
- Check business addresses and opening hours
- Identify businesses by category and location

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Yellow Pages tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Yellow Pages account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from yellowpages.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### How can I find businesses near a location?

Use Search businesses with a business type or name and a US city, state, or ZIP code.

### Can I find a business's phone number?

Search businesses returns listed phone numbers when available.

### Can I check business hours?

Search businesses returns opening hours or current open status when shown.

## Related

- [Yelp API](https://fous.com/tools/yelp.md): Yelp returns local business matches, public profiles, ratings and up to 60 publicly shown reviews; matches are unsponsored and Yelp-ordered, but later results may lack contact or location details.
- [Google Maps API](https://fous.com/tools/google-maps.md): Google Maps returns nearby places, public place details, up to 100 public reviews, and up to three routes; transit options vary by departure time.
- [Better Business Bureau API](https://fous.com/tools/better-business-bureau.md): Better Business Bureau provides business profiles, ratings, accreditation, reviews, alerts, and published complaints, with complaint details limited to those publicly displayed and newest first.
- [Trustpilot API](https://fous.com/tools/trustpilot.md): Trustpilot provides company ratings, reply and location details when available, recent public reviews, and company search results with ratings, review counts, categories, locations, and links.
- [OpenStreetMap API](https://fous.com/tools/openstreetmap.md): OpenStreetMap returns place coordinates, address details, nearby readable place information, and ordered place search results from contributor-created data; results reflect mapped features and may be incomplete or differ from landmarks.
- [AutoZone API](https://fous.com/tools/autozone.md): AutoZone finds parts and stores; engine fit may need confirmation, prices or warranties may be missing beyond 24 parts, and store listings cap at 25.
- [Apartments.com API](https://fous.com/tools/apartments-com.md): Apartments.com returns U.S. apartments and homes matching location and optional filters, plus community details; rent and availability may be missing or change.
- [OfferUp API](https://fous.com/tools/offerup.md): Local marketplace for buying and selling items.
- [All Maps tools](https://fous.com/tools/category/maps)