# DataBee SiteAtlas API Reference & Error Catalog (Full LLM Documentation Bundle)

DataBee SiteAtlas API turns any domain into clean traffic, SEO, audience, and competitor intelligence.

---

## 1. Global Specifications & Authentication

### Base URL
```
https://api.databee.dev
```

### Developer Console
Users can generate their free API key from the DataBee Developer Console at:
```
https://console.databee.dev
```

### Authentication Protocols
DataBee APIs require an API key passed via standard HTTP Bearer token authentication in the request headers (or optionally via `X-API-Key`):

```http
Authorization: Bearer YOUR_DATABEE_API_KEY
```
or
```http
X-API-Key: YOUR_DATABEE_API_KEY
```

Requests without a valid API key will receive an `HTTP 401 Unauthorized` response. Users can generate their free API key from the DataBee Developer Console at [https://console.databee.dev](https://console.databee.dev).

### Response Headers
Every API response returned by the DataBee Gateway includes standard metadata, usage, and security headers:

| Header Name | Type | Description |
| :--- | :--- | :--- |
| `Content-Type` | `string` | Always `application/json; charset=utf-8` |
| `X-Gateway-Service` | `string` | The API service identifier (e.g. `siteatlas`) |
| `X-Gateway-Credit-Cost` | `number` | Credits deducted for this API call (typically `1`) |
| `X-Gateway-Remaining-Credits` | `number` | Remaining credit balance in user wallet |
| `X-Gateway-Latency-Ms` | `number` | Response latency in milliseconds |
| `X-RateLimit-Limit` | `number` | Maximum allowed requests per second (RPS) |
| `X-Content-Type-Options` | `string` | Security header set to `nosniff` |
| `X-Frame-Options` | `string` | Security header set to `SAMEORIGIN` |
| `X-XSS-Protection` | `string` | Security header set to `1; mode=block` |

---

### Direct Access & RapidAPI Access

DataBee APIs are accessible directly via **Developer DataBee** (`https://api.databee.dev` / `https://console.databee.dev`) or via **RapidAPI Hub**.

#### Direct Portal Access (Developer DataBee)
- **Base URL**: `https://api.databee.dev`
- **Developer Console**: [https://console.databee.dev](https://console.databee.dev)
- **Authentication**: `Authorization: Bearer YOUR_DATABEE_API_KEY`

#### RapidAPI Access & Base URLs
RapidAPI provides proxy access using the following Base URLs:

1. **SiteAtlas API (Recommended Trademark-Free Listing)**
   - **Base URL**: `https://siteatlas.p.rapidapi.com`
   - **Host Header**: `x-rapidapi-host: siteatlas.p.rapidapi.com`
2. **Similarweb API Pro (Legacy Listing)**
   - **Base URL**: `https://similarweb-api-pro.p.rapidapi.com`
   - **Host Header**: `x-rapidapi-host: similarweb-api-pro.p.rapidapi.com`

> **Subscription Recommendation**: We strongly recommend users to subscribe to the trademark-free **SiteAtlas API** (`siteatlas.p.rapidapi.com`) listing. The *Similarweb API Pro* listing may be removed by RapidAPI at any time due to trademark compliance policies. Both listings route to the exact same DataBee backend infrastructure and return identical JSON payload responses.

#### Comparison Matrix: Direct Portal vs RapidAPI

| Feature | Direct Portal (`databee.dev` / `console.databee.dev`) | RapidAPI Marketplace |
| :--- | :--- | :--- |
| **Pricing & Cost** | Save up to 40% on credit pricing | Standard marketplace pricing |
| **Free Credits** | 500 Free Credits on sign-up (100 monthly + 400 trial) | No free credits included |
| **Credit Validity** | Credits valid up to 12 months | Monthly plan with no rollover |
| **Billing Precision** | Only successful requests charged | Charged against plan & overage rules |
| **Support & Refunds** | Direct 24/7 provider support | Support responses take 3-4 days |

#### RapidAPI Specific Request Headers & Code Examples

Calling via RapidAPI requires passing the RapidAPI proxy headers (`x-rapidapi-host`, `x-rapidapi-key`) **plus** optional platform `Authorization: Bearer <key>` header:

##### Recommended Trademark-Free RapidAPI Listing (`siteatlas.p.rapidapi.com`)
```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'
```

##### Legacy RapidAPI Listing (`similarweb-api-pro.p.rapidapi.com`)
```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'
```

---

## 2. API Endpoints

### 2.1 Site Overview (`GET /siteatlas/site-overview`)

Retrieves comprehensive domain metrics including estimated total visits, engagement, bounce rate, pages per visit, global/country/category ranks, top traffic geography, SEO keywords, and AI referral traffic (ChatGPT, Gemini, Claude, etc.).

- **HTTP Method**: `GET`
- **Path**: `/siteatlas/site-overview`
- **Credit Cost**: 1 Credit

#### Query Parameters

| Parameter | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `url` | `string` | Yes | Fully qualified domain name or domain string | `github.com` |

#### Example Request
```bash
curl -X GET "https://api.databee.dev/siteatlas/site-overview?url=github.com" \
  -H "Authorization: Bearer YOUR_DATABEE_API_KEY"
```

#### Example 200 OK Response Payload
```json
{
  "status": "success",
  "meta": {
    "request": { "url": "github.com" },
    "snapshot_date": "2026-07-01",
    "data_coverage": "complete"
  },
  "website": {
    "domain": "github.com",
    "title": "GitHub · Change is constant. GitHub keeps you ahead.",
    "description": "Join the world's most widely adopted, AI-powered developer platform...",
    "category": {
      "slug": "computers_electronics_and_technology/programming_and_developer_software",
      "name": "Computers Electronics and Technology > Programming and Developer Software"
    },
    "images": {
      "favicon_url": "https://site-images.similarcdn.com/image?url=github.com&t=2",
      "screenshot_desktop_url": "https://site-images.similarcdn.com/image?url=github.com&t=1",
      "screenshot_mobile_url": "https://site-images.similarcdn.com/image?url=github.com&t=4"
    },
    "flags": {
      "is_small_site": false,
      "is_from_google_analytics": false
    }
  },
  "rankings": {
    "global": { "rank": 49 },
    "country": { "country_code": "US", "rank": 79 },
    "category": {
      "category_slug": "computers_electronics_and_technology/programming_and_developer_software",
      "rank": 4
    }
  },
  "traffic": {
    "history": [
      { "month": "2026-05-01", "visits": 636075828 },
      { "month": "2026-06-01", "visits": 615239605 },
      { "month": "2026-07-01", "visits": 637885711 }
    ],
    "engagement": {
      "pages_per_visit": 5.87,
      "bounce_rate": 0.363,
      "average_visit_duration_seconds": 386.157
    },
    "sources_share": {
      "direct": 0.5233,
      "organic_search": 0.2511,
      "paid_search": 0.0002,
      "organic_social": 0.0916,
      "referrals": 0.0974,
      "generative_ai": 0.0208
    },
    "geography_share": [
      { "country_code": "US", "share": 0.1943 },
      { "country_code": "CN", "share": 0.1091 },
      { "country_code": "IN", "share": 0.1044 }
    ],
    "period": "2026-07"
  },
  "seo": {
    "top_keywords": [
      {
        "keyword": "github",
        "search_volume": 9503160,
        "cpc_usd": 1.66,
        "estimated_value_usd": 10930450
      }
    ]
  },
  "ai_referrals": {
    "total_visits": 11619886,
    "global_traffic_share": 0.0187,
    "platforms": [
      { "name": "chatgpt.com", "rank": 1, "share": 58.6502 },
      { "name": "gemini.google.com", "rank": 2, "share": 18.4489 }
    ]
  }
}
```

---

### 2.2 Site Similar (`GET /siteatlas/site-similar`)

Finds related websites, competitors, and similarity rankings for a target domain.

- **HTTP Method**: `GET`
- **Path**: `/siteatlas/site-similar`
- **Credit Cost**: 1 Credit

#### Query Parameters

| Parameter | Type | Required | Description | Example |
| :--- | :--- | :--- | :--- | :--- |
| `url` | `string` | Yes | Target domain | `github.com` |

#### Example Request
```bash
curl -X GET "https://api.databee.dev/siteatlas/site-similar?url=github.com" \
  -H "Authorization: Bearer YOUR_DATABEE_API_KEY"
```

#### Example 200 OK Response Payload
```json
{
  "status": "success",
  "meta": {
    "request": { "url": "github.com" },
    "snapshot_date": "2026-07-01",
    "total_results": 20
  },
  "source_site": {
    "domain": "github.com",
    "title": "GitHub · Change is constant...",
    "category": "Computers Electronics and Technology > Programming and Developer Software"
  },
  "similar_sites": [
    {
      "rank": 1,
      "domain": "gitlab.com",
      "title": "The AI-powered DevSecOps Platform | GitLab",
      "similarity_score": 0.942,
      "category": "Computers Electronics and Technology > Programming and Developer Software",
      "favicon_url": "https://site-images.similarcdn.com/image?url=gitlab.com&t=2"
    },
    {
      "rank": 2,
      "domain": "bitbucket.org",
      "title": "Bitbucket | Git solution for teams using Jira",
      "similarity_score": 0.885,
      "category": "Computers Electronics and Technology > Programming and Developer Software",
      "favicon_url": "https://site-images.similarcdn.com/image?url=bitbucket.org&t=2"
    }
  ]
}
```

---

### 2.3 Country Metadata (`GET /siteatlas/country-metadata`)

Returns ISO 3166-1 numeric, alpha-2, and alpha-3 country code mappings.

- **HTTP Method**: `GET`
- **Path**: `/siteatlas/country-metadata`
- **Credit Cost**: 1 Credit

#### Example Request
```bash
curl -X GET "https://api.databee.dev/siteatlas/country-metadata" \
  -H "Authorization: Bearer YOUR_DATABEE_API_KEY"
```

#### Example 200 OK Response Payload
```json
{
  "status": "success",
  "meta": { "count": 249, "standard": "ISO 3166-1" },
  "countries": [
    { "name": "United States", "alpha2": "US", "alpha3": "USA", "numeric": "840" },
    { "name": "India", "alpha2": "IN", "alpha3": "IND", "numeric": "356" }
  ]
}
```

---

### 2.4 Legacy / Deprecated Endpoints

- `GET /siteatlas/similar-sites` (Alias for `/siteatlas/site-similar`)
- `GET /siteatlas/website-overview` (Alias for `/siteatlas/site-overview`)

---

## 3. Exhaustive Error Status Codes Catalog

| Status Code | Code | Message / Trigger |
| :--- | :--- | :--- |
| `400 Bad Request` | `MISSING_PARAMETER` | Query parameter `url` missing |
| `400 Bad Request` | `INVALID_DOMAIN` | Target `url` invalid or malformed domain string |
| `401 Unauthorized` | `Unauthorized` | Missing or invalid API key (Generate key at https://console.databee.dev) |
| `402 Payment Required` | `Payment Required` | Zero or insufficient wallet credits (Top up at https://console.databee.dev) |
| `404 Not Found` | `Not Found` | Unknown API path or service route |
| `405 Method Not Allowed` | `Method Not Allowed` | Unsupported HTTP verb (POST/PUT/DELETE) |
| `413 Payload Too Large` | `Payload Too Large` | Request body exceeds 10MB limit |
| `429 Too Many Requests` | `Too Many Requests` | Request frequency exceeds allowed RPS limit |
| `500 Internal Error` | `Internal Server Error` | Unhandled backend processing error |
| `502 Bad Gateway` | `Bad Gateway` | Upstream API service unreachable (Credits refunded) |
| `504 Gateway Timeout` | `Gateway Timeout` | Upstream API service execution timeout (Credits refunded) |