# DataBee SiteAtlas API Documentation

> DataBee SiteAtlas API turns any web domain into clean traffic intelligence, engagement metrics, SEO rankings, competitor insights, and AI referral analytics (ChatGPT, Gemini, Claude).

## API Specifications

- Base URL: `https://api.databee.dev`
- Developer Console: [https://console.databee.dev](https://console.databee.dev)
- Direct Portal: [https://databee.dev](https://databee.dev)
- Authentication: `Authorization: Bearer YOUR_DATABEE_API_KEY` or `X-API-Key: YOUR_DATABEE_API_KEY`
- Documentation Portal: [https://docs.databee.dev](https://docs.databee.dev)
- Full LLM Documentation Bundle: [https://docs.databee.dev/llms-full.txt](https://docs.databee.dev/llms-full.txt)
- Machine-Readable OpenAPI 3.1 Spec: [https://docs.databee.dev/openapi.json](https://docs.databee.dev/openapi.json)

## Core Endpoints

- `GET /siteatlas/site-overview`: Comprehensive domain intelligence including visits history, engagement (bounce rate, duration, pages/visit), category & global ranks, top SEO keywords, traffic share by channel, top countries, and AI referral traffic shares (ChatGPT, Gemini, Claude, etc.).
- `GET /siteatlas/site-similar`: Related websites, competitor domains, similarity confidence scores (0.00 to 1.00), and category classifications for target domain.
- `GET /siteatlas/country-metadata`: ISO 3166-1 country reference mapping (alpha-2, alpha-3, numeric codes, names) used in SiteAtlas reports.

## Legacy Endpoints (Backward Compatible)

- `GET /siteatlas/website-overview`: Legacy alias for `/siteatlas/site-overview`.
- `GET /siteatlas/similar-sites`: Legacy alias for `/siteatlas/site-similar`.

## Response Headers

- `Content-Type`: `application/json; charset=utf-8`
- `X-Gateway-Service`: Service identifier (`siteatlas`)
- `X-Gateway-Credit-Cost`: Credit cost per request (typically `1`)
- `X-Gateway-Remaining-Credits`: Wallet credit balance remaining
- `X-Gateway-Latency-Ms`: Execution latency in milliseconds
- `X-RateLimit-Limit`: Maximum allowable requests per second (RPS)
- `X-Content-Type-Options`: Security header (`nosniff`)
- `X-Frame-Options`: Security header (`SAMEORIGIN`)
- `X-XSS-Protection`: Security header (`1; mode=block`)

## Error Status Codes

- `400 Bad Request`: Missing parameter (`MISSING_PARAMETER`) or invalid domain format (`INVALID_DOMAIN`)
- `401 Unauthorized`: Missing or invalid API key (Generate free key at https://console.databee.dev)
- `402 Payment Required`: Zero or insufficient wallet credits
- `404 Not Found`: Route or service not found
- `405 Method Not Allowed`: HTTP verb not supported
- `429 Too Many Requests`: Rate limit exceeded
- `502 Bad Gateway` / `504 Gateway Timeout`: Upstream service errors (Credits automatically refunded)

## Direct Access vs RapidAPI Base URLs

DataBee APIs can be accessed directly or via RapidAPI Hub:

- **Direct Gateway Base URL**: `https://api.databee.dev` (Generate key at `https://console.databee.dev`)
- **RapidAPI Base URL (Trademark-Free Recommended)**: `https://siteatlas.p.rapidapi.com`
- **RapidAPI Base URL (Legacy Listing)**: `https://similarweb-api-pro.p.rapidapi.com`

### RapidAPI Specific Request Headers

Pass RapidAPI headers (`x-rapidapi-host` and `x-rapidapi-key`). On legacy listings or when linking DataBee accounts, also pass `Authorization: Bearer YOUR_DATABEE_API_KEY`.

#### cURL via SiteAtlas (Recommended Trademark-Free Listing)
```bash
curl --request GET \
  --url 'https://siteatlas.p.rapidapi.com/site-overview?url=github.com' \
  --header 'Content-Type: application/json' \
  --header 'x-rapidapi-host: siteatlas.p.rapidapi.com' \
  --header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY'
```

#### cURL via Similarweb API Pro (Legacy Listing)
```bash
curl --location 'https://similarweb-api-pro.p.rapidapi.com/site-overview?url=microsoft.com' \
  --header 'x-rapidapi-host: similarweb-api-pro.p.rapidapi.com' \
  --header 'x-rapidapi-key: YOUR_RAPIDAPI_KEY' \
  --header 'Authorization: Bearer YOUR_DATABEE_API_KEY'
```