Brightdata Hello World

---
name: brightdata-hello-world
description: 'Create a minimal working Bright Data example.

  Use when starting a new Bright Data integration, testing your setup,

  or learning basic Bright Data API patterns.

  Trigger with phrases like "brightdata hello world", "brightdata example",

  "brightdata quick start", "simple brightdata code".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(node:*)
version: 1.6.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- scraping
- data
- brightdata
compatibility: Designed for Claude Code
---
# Bright Data Hello World

## Overview

Scrape a real webpage through Bright Data's Web Unlocker proxy. Web Unlocker handles CAPTCHAs, fingerprinting, and retries automatically — you send a normal HTTP request through the proxy endpoint at `brd.superproxy.io:33335`.

## Prerequisites

- Completed `brightdata-install-auth` setup
- Web Unlocker zone active in Bright Data control panel
- `brd-ca.crt` SSL certificate downloaded

## Instructions

### Step 1: Scrape via Web Unlocker Proxy (Node.js)

```typescript
// hello-brightdata.ts
import axios from 'axios';
import https from 'https';
import 'dotenv/config';

const { BRIGHTDATA_CUSTOMER_ID, BRIGHTDATA_ZONE, BRIGHTDATA_ZONE_PASSWORD } = process.env;

const proxy = {
  host: 'brd.superproxy.io',
  port: 33335,
  auth: {
    username: `brd-customer-${BRIGHTDATA_CUSTOMER_ID}-zone-${BRIGHTDATA_ZONE}`,
    password: BRIGHTDATA_ZONE_PASSWORD!,
  },
};

async function scrape(url: string) {
  const response = await axios.get(url, {
    proxy,
    httpsAgent: new https.Agent({ rejectUnauthorized: false }),
    timeout: 60000,
  });
  console.log(`Status: ${response.status}`);
  console.log(`Content length: ${response.data.length} chars`);
  console.log(response.data.substring(0, 500));
  return response.data;
}

scrape('https://example.com').catch(console.error);
```

### Step 2: Scrape via REST API

```typescript
// hello-brightdata-api.ts
import 'dotenv/config';

async function scrapeViaAPI(url: string) {
  const response = await fetch('https://api.brightdata.com/request', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BRIGHTDATA_API_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      zone: process.env.BRIGHTDATA_ZONE,
      url,
      format: 'raw',
    }),
  });
  const html = await response.text();
  console.log(`Status: ${response.status}, Length: ${html.length}`);
  return html;
}

scrapeViaAPI('https://example.com').catch(console.error);
```

### Step 3: Python Version

```python
# hello_brightdata.py
import os, requests
from dotenv import load_dotenv

load_dotenv()
proxy_url = (
    f"http://brd-customer-{os.environ['BRIGHTDATA_CUSTOMER_ID']}"
    f"-zone-{os.environ['BRIGHTDATA_ZONE']}"
    f":{os.environ['BRIGHTDATA_ZONE_PASSWORD']}"
    f"@brd.superproxy.io:33335"
)
response = requests.get(
    'https://example.com',
    proxies={'http': proxy_url, 'https': proxy_url},
    verify='./brd-ca.crt',
    timeout=60,
)
print(f"Status: {response.status_code}, Length: {len(response.text)}")
```

## Geo-Targeting

Add country or city targeting to the proxy username:

```typescript
// Country-level
const username = `brd-customer-${ID}-zone-${ZONE}-country-us`;
// City-level
const username2 = `brd-customer-${ID}-zone-${ZONE}-country-us-city-newyork`;
```

## Output

- Successful HTTP response through Bright Data proxy
- HTML content of the target page
- Rotated IP address per request

## Examples

Use a provider-approved test target or a domain you control, constrain the request to the minimum path and geography needed, and retain only the status and request identifier in shared logs. Verify that collection is permitted by applicable law, the target's terms, and the organization's policy before moving beyond a synthetic demonstration.

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| `407 Proxy Auth Required` | Bad credentials | Check `brd-customer-{ID}-zone-{ZONE}` format |
| `502 Bad Gateway` | Target site blocked | Web Unlocker retries; increase timeout |
| `ETIMEDOUT` | CAPTCHA solving delay | Set timeout to 60-120s |
| Empty response | Zone inactive | Verify zone in control panel |

## Resources

- [Web Unlocker Docs](https://docs.brightdata.com/scraping-automation/web-unlocker/send-your-first-request)
- Web Unlocker API
- Geo-Targeting

## Next Steps

Proceed to `brightdata-local-dev-loop` for development workflow setup.