Name: Domain Profile API
Brand: quickpod
SKU: api-quickpod-aiquick-domain-profile
Availability: InStock
Author: API Market

Anil Singh

# Domain Profile API

## Overview

The Domain Profile API is a powerful and comprehensive tool designed to analyze any target URL or domain and return a detailed, structured profile of the website. It acts as a sophisticated profiler, fetching page content, extracting crucial metadata, performing advanced lookups, and classifying site intent. This API is essential for developers and businesses needing a quick, actionable understanding of a website's characteristics, performance, and topical relevance.

Leverage the Domain Profile API to get a deep, structured read on any website before critical processes like enrichment, lead scoring, competitive research, or SEO triage. The flexible, open-ended JSON response ensures that you receive precisely the data your workflow requires without adhering to a rigid document shape.

For instance, providing `msn.com` as a target will yield insights into its site classification and a list of highly relevant keywords, enabling robust downstream analysis. This API is perfectly suited for automated pipelines that process numerous domains, require consistent comparisons, or need to attach rich, site-level context to other datasets.

Because the output schema is intentionally flexible, integrate by focusing on the specific fields your workflow utilizes and treat the response as a dynamic, comprehensive site profile payload.

## Features

- **Comprehensive Data Extraction:** Fetches a target URL/domain using a browser-like user agent and extracts key on-page elements including title, description, keywords, canonical URL, robots meta tags, and Open Graph properties.
- **Performance & SEO Analysis:** Provides heuristic analysis of website performance (status code, response time, content length) and SEO health (title/description length, H1 count, canonical/robots presence).
- **External Lookups & Enrichment:** Integrates with external services to provide domain authority/page rank data and performs advanced keyword extraction and keyword-domain lookups.
- **Website Classification:** Classifies the page's intent and taxonomy using a unified classification API, providing structured labels and confidence scores.
- **Visual Snapshot:** Generates and provides a deterministic URL for a screenshot of the target page, offering a visual reference of the website.
- **Flexible Output Schema:** Returns an open-ended JSON object, allowing for dynamic and extensible profile data tailored to diverse use cases without a fixed structure.
- **Real-time Processing:** Delivers immediate, synchronous results for rapid integration into applications and workflows requiring instant domain intelligence.

## Use Cases

- **Lead Scoring & Sales Intelligence:** Automatically enrich lead profiles by instantly analyzing prospective client websites. Identify their industry, key services, SEO performance, and online presence to prioritize outreach and personalize sales pitches.
- **Competitive Research & Market Analysis:** Gain a competitive edge by programmatically profiling competitors' websites. Compare their SEO strengths, content strategies, and market positioning to identify opportunities and threats in real-time.
- **SEO Audit & Content Strategy:** Conduct quick SEO triage for large sets of URLs. Identify missing meta descriptions, canonical issues, or low-performing pages. Extract relevant keywords to inform content creation and optimization strategies.
- **Fraud Detection & Risk Assessment:** Analyze unknown or suspicious URLs to quickly assess their legitimacy and content. Identify characteristics that might indicate phishing attempts, spam, or malicious intent, enhancing cybersecurity measures.
- **Ad Tech & Publisher Targeting:** Profile publisher websites for ad targeting and inventory quality. Understand their topical focus, audience relevance, and on-page SEO factors to optimize ad placements and ensure brand safety.

## Pricing

The Domain Profile API operates on a usage-based pricing model.
- 1 API unit equals 1 image processed.
- Different pricing tiers are available based on usage volume, offering cost-effectiveness for various scales of operations.

## API Documentation

### Base URL

All API requests should be made to: `https://prod.api.market/api/v1/quickpod/aiquick-domain-profile`

### Authentication

Authentication is handled via API key. Include your API key in the request header for all API calls:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Endpoints

#### GET /health

Checks the health and status of the service.

- **Summary:** Service health
- **Tags:** Health
- **Authentication:** Required (via `x-api-market-key` header)

**Request Example:**
```bash
curl -X GET "https://prod.api.market/api/v1/quickpod/aiquick-domain-profile/health" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example (200 OK):**
```json
{
  "ok": true,
  "service": "aiquick-domain-profile",
  "max_inflight": 100
}
```

#### POST /domain-profile

Builds a complete profile for a given URL or domain.

- **Summary:** Build complete domain profile
- **Description:** Fetches and analyzes a URL/domain, enriches with keyword and pagerank lookups, and classifies via classify-api.
- **Tags:** DomainProfile
- **Authentication:** Required (via `x-api-market-key` header)

**Request Body (`application/json`):**
| Field            | Type    | Description                                   | Required | Default | Min | Max | Example                     |
| :--------------- | :------ | :-------------------------------------------- | :------- | :------ | :-- | :-- | :-------------------------- |
| `target`         | string  | URL or domain to analyze.                     | Yes      | -       | -   | -   | `"msn.com"`                 |
| `top_k_keywords` | integer | Number of top keywords to return.             | No       | 10      | 1   | 30  | `10`                        |
| `classify_top_k` | integer | Number of top classifications to return.      | No       | 3       | 1   | 20  | `3`                         |

**Request Examples:**

**Domain Input:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-domain-profile/domain-profile" \
     -H "Content-Type: application/json" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -d '{
       "target": "msn.com",
       "top_k_keywords": 10,
       "classify_top_k": 3
     }'
```

**URL Input:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-domain-profile/domain-profile" \
     -H "Content-Type: application/json" \
     -H "x-api-market-key: YOUR_API_MARKET_KEY" \
     -d '{
       "target": "https://www.nytimes.com",
       "top_k_keywords": 12,
       "classify_top_k": 5
     }'
```

**Response Example (200 OK):**
```json
{
  "target": "msn.com",
  "normalized": {
    "url": "https://msn.com",
    "domain": "msn.com"
  },
  "snapshot": {
    "title": "MSN | Outlook, Office, Skype, Bing, Breaking News, and Latest Videos",
    "description": "Your customizable and curated collection of the best in trusted news.",
    "keywords": "msn, news, outlook",
    "canonical_url": "https://www.msn.com/",
    "robots": "index, follow",
    "open_graph": {
      "title": "MSN",
      "description": "Trusted news and stories."
    },
    "h1_count": 1
  },
  "image": {
    "preview_url": "https://screens.front-page.com/msn-com--.jpeg"
  },
  "analysis": {
    "performance": {
      "status_code": 200,
      "final_url": "https://www.msn.com/",
      "redirect_count": 1,
      "response_time_ms": 643.72,
      "content_length_bytes": 185332,
      "content_type": "text/html; charset=utf-8",
      "content_encoding": "br",
      "cache_control": "public, max-age=300",
      "server": "envoy",
      "score": 90
    },
    "seo": {
      "title_length": 68,
      "description_length": 78,
      "keyword_count": 3,
      "has_canonical": true,
      "has_robots": true,
      "h1_count": 1,
      "has_open_graph_title": true,
      "has_open_graph_description": true,
      "score": 94
    }
  },
  "lookups": {
    "pagerank": {
      "query": "msn.com",
      "found": true
    },
    "keyword_extract": {
      "success": true
    },
    "keyword_domain_lookup": {
      "query": "trusted news outlook"
    }
  },
  "classification": {
    "provider": "classify-api",
    "input": {
      "title": "MSN | Outlook, Office, Skype, Bing, Breaking News, and Latest Videos",
      "description": "Your customizable and curated collection of the best in trusted news.",
      "keywords": [
        "news",
        "outlook"
      ]
    },
    "result": {
      "labels": [
        {
          "tier": "tier1",
          "label": "News",
          "score": 0.94
        }
      ]
    }
  },
  "meta": {
    "request_id": "74f2ec85-8a0e-4b8f-bec9-25aa89f4f08f",
    "fetched_url": "https://www.msn.com/",
    "fetched_status": 200
  }
}
```

## Status Codes

- **200 OK:** Request successful. The API processed the input and returned the requested domain profile.
- **201 Created:** (Not applicable for this API's current endpoints) Resource successfully created.
- **400 Bad Request:** Invalid input parameters or malformed request body. Check your request payload against the schema requirements.
- **401 Unauthorized:** Missing or invalid API key. Ensure `x-api-market-key` header is present and contains a valid key.
```json
{
  "detail": "Invalid or missing proxy secret"
}
```
- **403 Forbidden:** Valid API key but insufficient permissions. This typically indicates a problem with your API key's access scope.
- **404 Not Found:** Resource not found. This could mean an incorrect endpoint path.
- **422 Unprocessable Entity:** Request validation failed. The server understands the request but cannot process it due to semantic errors in the input data (e.g., `target` is not a valid URL/domain).
```json
{
  "detail": [
    {
      "loc": [
        "body",
        "target"
      ],
      "msg": "value is not a valid url or domain",
      "type": "value_error.url"
    }
  ]
}
```
- **429 Too Many Requests:** Rate limit exceeded. You have sent too many requests in a given amount of time. Implement retry logic with exponential backoff.
- **500 Internal Server Error:** A server-side error occurred. This is usually an unexpected error on the API's end. If this persists, please contact support.
- **502 Bad Gateway:** Failed to fetch target page. The API could not reach or process the specified `target` URL/domain.
```json
{
  "detail": "Failed to fetch target page"
}
```
- **503 Service Unavailable:** Service temporarily unavailable. The API might be undergoing maintenance or experiencing high load. Implement retry logic.
- **504 Gateway Timeout:** Timeout while fetching target page. The API took too long to fetch and analyze the specified `target` URL/domain.
```json
{
  "detail": "Timeout while fetching target page"
}
```

## Rate Limits

Specific rate limits are applied to prevent abuse and ensure fair usage for all clients. If you exceed your allocated rate limit, the API will respond with a `429 Too Many Requests` status code. Details on your specific rate limits are typically available in your API.market dashboard.

To handle rate limits effectively:
- Monitor for `429` responses.
- Implement an exponential backoff strategy for retries. For example, wait 1 second, then 2, then 4, etc., between attempts.
- Ensure your client application respects any `Retry-After` headers that may be included in `429` responses.

## Error Handling

Robust error handling is crucial for reliable API integrations.

- **Interpreting Error Responses:** Always check the HTTP status code of the API response. Status codes in the `4xx` range indicate client-side errors (e.g., bad input, authentication issues), while `5xx` codes indicate server-side problems. Error responses typically include a JSON body with a `detail` field providing more context.
- **Common Errors and Resolutions:**
  - **401 Unauthorized:** Double-check that your `x-api-market-key` header is correctly set and that the key is valid and active.
    - **422 Unprocessable Entity:** Review the `target` parameter in your request body. Ensure it's a well-formed URL or domain. Check other input parameters (`top_k_keywords`, `classify_top_k`) for valid types and ranges.
    - **502 Bad Gateway / 504 Gateway Timeout:** These often indicate issues with the target website itself (e.g., website down, slow to respond, blocking crawlers). Consider retrying the request for the same target after a short delay, or if it's a critical target, investigate its availability.
- **Recommended Retry Strategies:** For transient errors like `429 Too Many Requests`, `503 Service Unavailable`, `502 Bad Gateway`, or `504 Gateway Timeout`, implement retry logic with exponential backoff. Start with a short delay (e.g., 1 second) and increase the delay for subsequent retries. Limit the total number of retries to prevent infinite loops.

**Error Response Example (400 Bad Request):**
```json
{
  "detail": "The 'target' parameter is required in the request body."
}
```

## FAQ

**What kind of URLs or domains can I send to the API?**

You can send any valid URL (e.g., `https://example.com/page`) or a bare domain (e.g., `example.com`). The API will attempt to fetch and analyze it.

**Is the API synchronous or asynchronous?**

The Domain Profile API is **synchronous**. You send a request, and the API responds directly with the complete domain profile. There's no need to poll for results.

**How accurate is the website classification?**

The API uses an integrated `classify-api` for page intent and taxonomy, which is based on advanced AI models. The response includes confidence scores for each classification label, allowing you to use the results with appropriate thresholds for your application.

**What if the target website is down or takes too long to respond?**

The API will return an error, typically a `502 Bad Gateway` (failed to fetch) or `504 Gateway Timeout` (timeout while fetching). Implement robust error handling and retry mechanisms in your application.

**Can I get a screenshot of the website?**

Yes, the API provides a deterministic URL for a screenshot in the `image.preview_url` field of the response. This URL points to an image of the target page.

**How often is the data refreshed for a given domain?**

Each API call performs a fresh analysis of the target URL/domain. If you need updated information, make a new request. For frequently accessed domains, consider implementing client-side caching.

**What kind of keywords does the API extract?**

The API performs keyword extraction to identify the most relevant terms associated with the target page's content. These are useful for SEO, content analysis, and understanding the page's topical focus.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Build a complete profile for any URL or domain in a single request, consolidating site signals for SEO research, lead scoring and competitor analysis.