StoreCensus API Documentation

v1Base URL: https://www.storecensus.com

Introduction

The StoreCensus API provides programmatic access to comprehensive e-commerce intelligence data. Our RESTful API delivers structured, reliable data about online stores and businesses to power your applications, integrations, and workflows.

Whether you're building lead generation tools, enriching CRM data, conducting market research, or developing competitive analysis platforms, our API provides the foundation for data-driven e-commerce insights.

All API responses are returned in JSON format with consistent structure, comprehensive error handling, and enterprise-grade reliability. Authentication is handled via Bearer tokens with built-in rate limiting to ensure optimal performance for all users.

Authentication

The StoreCensus API uses Bearer Token Authentication. You must include your API key in the Authorization header of all requests.

Authentication Method

Authorization: Bearer your.api.key

API keys can be generated on the API page of your StoreCensus account after logging in.

Authentication Errors

Status Code	Error	Description
401	{'error': 'Missing API key'}	No API key was provided in the request
401	{'error': 'Invalid Authorization header format. Expected: Bearer your.api.key'}	The Authorization header format is incorrect
401	{'error': 'API key cannot be empty'}	An empty API key was provided
401	{'error': 'Invalid API key or inactive subscription'}	The API key is invalid or the subscription is not active

Rate Limits

The StoreCensus API implements rate limiting based on your subscription plan. Rate limits are applied on a per-API-key basis.

Rate Limit Plans

Plan	Rate Limit
Other Plans	6 requests per second
Premium Plan	30 requests per second

Rate Limit Implementation

Rate limits are calculated using a 1-second sliding window
When rate limits are exceeded, the API returns a 429 Too Many Requests response
The response includes a Retry-After header indicating when you can make another request
Rate limit implementation uses in-memory caching for optimal performance

Rate Limit Exceeded Response:

{'error': 'Rate limit exceeded'}

Error Handling

The StoreCensus API uses standard HTTP status codes to indicate the success or failure of requests. All errors are returned in a consistent JSON format.

Status Code	Description
400 Bad Request	The request was malformed or missing required parameters
401 Unauthorized	Authentication failed or was not provided
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	An error occurred on the server

Error Response Format

All errors are returned in a consistent JSON format with an error field containing a description of the error:

{'error': 'Description of the error'}

The /website Endpoint

Endpoint Details

URL	`GET /api/v1/website/{domain}`
Description	Retrieve comprehensive e-commerce intelligence data for a specific website domain
Authentication	Required (Bearer token)
Rate Limited	Yes (based on subscription plan)

Path Parameters

Parameter	Description
`domain`required	The domain name to analyze (e.g., "example-store.com")

Request Example

curl -X GET "https://www.storecensus.com/api/v1/website/example-store.com" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json"

Response Format

The API returns comprehensive domain data organized into logical sections for enterprise-level consumption:

{
  "basic_info": {
    "domain": "string",
    "company_name": "string",
    "description": "string",
    "vertical": "string",
    "product_categories": "string",
    "employee_count": number,
    "website_created_at": "string",
    "language": "string",
    "password_protected": boolean
  },
  "contact_info": {
    "emails": [
      {
        "email": "string",
        "email_type": "string",
        "validated": boolean,
        "found_date": "string"
      }
    ],
    "phone": "string",
    "email_count": number,
    "phone_count": number,
    "contact_available": boolean
  },
  "location_info": {
    "address": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "zip_code": "string",
    "timezone": "string"
  },
  "social_media": {
    "facebook": "string",
    "twitter": "string",
    "instagram": "string",
    "linkedin": "string",
    "youtube": "string",
    "tiktok": "string",
    "pinterest": "string",
    "snapchat": "string",
    "whatsapp": "string",
    "telegram": "string",
    "discord": "string",
    "reddit": "string",
    "twitch": "string"
  },
  "ecommerce_info": {
    "platform": "string",
    "theme": "string",
    "currency": "string",
    "product_count": number,
    "variant_count": number,
    "average_product_price": number
  },
  "financial_info": {
    "estimated_monthly_revenue": number,
    "estimated_tech_spend": number,
    "estimated_app_spend": number,
    "estimated_technology_spend": number
  },
  "traffic_analytics": {
    "estimated_visits": number,
    "keywords": {
      "keyword": "string"
    },
    "sources": {
      "keyword": "string"
    },
    "bouncerate": {
      "num": number
    },
    "category": {
      "keyword": "string"
    },
    "globalrank": {
      "long": number
    },
    "pagepervisit": {
      "num": number
    },
    "screenshot": {
      "keyword": "string"
    },
    "timeonsite": {
      "num": number
    },
    "visits": {
      "long": number
    }
  },
  "technical_info": {
    "technologies": [
      {
        "technology_name": "string",
        "installed": boolean,
        "confidence": number,
        "effective_from": "string",
        "effective_to": "string",
        "observed_at": "string"
      }
    ],
    "last_crawled": "string"
  },
  "apps_integrations": {
    "shopify_apps": [
      {
        "name": "string",
        "handle": "string",
        "category": "string",
        "description": "string",
        "developer": "string",
        "rating": number,
        "review_count": number,
        "pricing": "string",
        "icon_url": "string",
        "app_store_url": "string",
        "installed": boolean,
        "last_detected": "string",
        "first_detected": "string",
        "plans": "array",
        "reviews": "array"
      }
    ]
  },
  "data_metadata": {
    "lead_id": "string",
    "last_updated": "string",
    "data_source": "string",
    "api_version": "string"
  }
}

Example Response

{
  "basic_info": {
    "domain": "example-store.com",
    "company_name": "Example Store Inc",
    "description": "Premium e-commerce retailer specializing in consumer electronics and accessories with a focus on quality and innovation.",
    "vertical": "Electronics & Gadgets",
    "product_categories": "electronics;gadgets;accessories;audio;wearables;smart-devices;headphones;speakers;cables;chargers",
    "employee_count": 150,
    "website_created_at": null,
    "language": "English",
    "password_protected": false
  },
  "contact_info": {
    "emails": [
      {
        "email": "founder@example-store.com",
        "email_type": "founder_personal",
        "validated": false,
        "found_date": "2024-08-25T17:22:47"
      },
      {
        "email": "info@example-store.com",
        "email_type": "founder_personal",
        "validated": false,
        "found_date": "2024-08-25T17:22:47"
      },
      {
        "email": "support@example-store.com",
        "email_type": "general_info_support",
        "validated": false,
        "found_date": "2024-08-25T17:22:47"
      }
    ],
    "phone": null,
    "email_count": 3,
    "phone_count": 0,
    "contact_available": true
  },
  "location_info": {
    "address": null,
    "city": "San Francisco",
    "state": null,
    "country": "US",
    "zip_code": null,
    "timezone": null
  },
  "social_media": {
    "facebook": "facebook.com/examplestore",
    "twitter": "twitter.com/examplestore",
    "instagram": "https://www.instagram.com/example_store",
    "linkedin": "linkedin.com/company/example-store",
    "youtube": "https://www.youtube.com/channel/UCexamplestore123",
    "tiktok": null,
    "pinterest": "pinterest.com/examplestore",
    "snapchat": null,
    "whatsapp": null,
    "telegram": null,
    "discord": null,
    "reddit": null,
    "twitch": null
  },
  "ecommerce_info": {
    "platform": "Shopify",
    "theme": "Dawn",
    "currency": "usd",
    "product_count": 450,
    "variant_count": 1200,
    "average_product_price": 89.99
  },
  "financial_info": {
    "estimated_monthly_revenue": 125000,
    "estimated_tech_spend": 2500,
    "estimated_app_spend": 800,
    "estimated_technology_spend": null
  },
  "traffic_analytics": {
    "estimated_visits": null,
    "keywords": {
      "keyword": "[{\"cpc\":0.75,\"estimatedvalue\":12500,\"name\":\"electronics store\",\"volume\":45000},{\"cpc\":0.45,\"estimatedvalue\":8200,\"name\":\"wireless headphones\",\"volume\":18000}]"
    },
    "sources": {
      "keyword": "{\"social\":0.15,\"paid referrals\":0.08,\"mail\":0.02,\"referrals\":0.12,\"search\":0.45,\"direct\":0.18}"
    },
    "bouncerate": {
      "num": 0.32
    },
    "category": {
      "keyword": "e-commerce_and_shopping/electronics"
    },
    "globalrank": {
      "long": 25000
    },
    "pagepervisit": {
      "num": 2.8
    },
    "screenshot": {
      "keyword": "https://example.com/screenshot.jpg"
    },
    "timeonsite": {
      "num": 180.5
    },
    "visits": {
      "long": 85000
    }
  },
  "technical_info": {
    "technologies": [
      {
        "technology_name": "Google Analytics",
        "installed": true,
        "confidence": 100,
        "effective_from": "2024-01-15T10:30:00",
        "effective_to": "9999-12-31T00:00:00",
        "observed_at": "2024-01-15T10:30:00"
      },
      {
        "technology_name": "Facebook Pixel",
        "installed": true,
        "confidence": 100,
        "effective_from": "2024-01-15T10:30:00",
        "effective_to": "9999-12-31T00:00:00",
        "observed_at": "2024-01-15T10:30:00"
      }
    ],
    "last_crawled": "2024-12-01T10:30:00"
  },
  "apps_integrations": {
    "shopify_apps": [
      {
        "name": "Email Marketing Pro",
        "handle": "email-marketing-pro",
        "category": null,
        "description": "Advanced email marketing and automation platform for e-commerce stores.",
        "developer": "marketing-solutions-inc",
        "rating": null,
        "review_count": null,
        "pricing": null,
        "icon_url": "https://example.com/app-icon.png",
        "app_store_url": null,
        "installed": true,
        "last_detected": "2024-11-15T08:30:00",
        "first_detected": "2024-06-01T12:00:00",
        "plans": [
          {
            "updated_at": "2024-11-01T10:00:00",
            "price_string": "Free",
            "price": 0,
            "is_free": true,
            "created_at": "2024-06-01T10:00:00",
            "description": "Up to 1000 emails per month, Basic templates",
            "free_trial": "",
            "plan_name": "Starter",
            "pricing_id": 1001
          },
          {
            "updated_at": "2024-11-01T10:00:00",
            "price_string": "$29.99 / month",
            "price": 29.99,
            "is_free": false,
            "created_at": "2024-06-01T10:00:00",
            "description": "Unlimited emails, Advanced automation, Analytics",
            "free_trial": "",
            "plan_name": "Professional",
            "pricing_id": 1002
          }
        ],
        "reviews": null
      },
      {
        "name": "Shipping Solutions",
        "handle": "shipping-solutions",
        "category": null,
        "description": "Comprehensive shipping and fulfillment management for online stores.",
        "developer": "logistics-tech-co",
        "rating": null,
        "review_count": null,
        "pricing": null,
        "icon_url": "https://example.com/shipping-icon.png",
        "app_store_url": null,
        "installed": true,
        "last_detected": "2024-11-15T08:30:00",
        "first_detected": "2024-07-10T14:20:00",
        "plans": [
          {
            "updated_at": "2024-10-15T12:00:00",
            "price_string": "Free",
            "price": 0,
            "is_free": true,
            "created_at": "2024-07-10T12:00:00",
            "description": "Basic shipping features",
            "free_trial": "",
            "plan_name": "Basic",
            "pricing_id": 2001
          },
          {
            "updated_at": "2024-10-15T12:00:00",
            "price_string": "$19.99 / month",
            "price": 19.99,
            "is_free": false,
            "created_at": "2024-07-10T12:00:00",
            "description": "Advanced shipping options, Multi-carrier support",
            "free_trial": "",
            "plan_name": "Premium",
            "pricing_id": 2002
          }
        ],
        "reviews": null
      }
    ]
  },
  "data_metadata": {
    "lead_id": 12345,
    "last_updated": "2024-12-01T10:30:00",
    "data_source": "StoreCensus",
    "api_version": "v1"
  }
}

Empty Response

When no data is found for a domain:

{}