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
Professional	6 requests per second
Enterprise	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 or lead_id.✨ Supports lead_id (integer) for direct lookup
Authentication	Required (Bearer token)
Rate Limited	Yes (based on subscription plan)

💡 Flexible Lookup: This endpoint intelligently detects the input type. Pass a domain name (e.g., "example-store.com") for domain-based search, or pass an integer (e.g., "12345") for direct lead_id lookup. No need for separate endpoints!

Path Parameters

Parameter	Description
`domain`required	The domain name to analyze (e.g., "example-store.com") or lead_id (e.g., "12345"). If the parameter is numeric, it will be treated as a lead_id for direct lookup.

Query Parameters

Parameter	Description
`sections`optional	Comma-separated list of sections to include in the response. Available sections:`basic_info`,`contact_info`,`location_info`,`social_media`,`ecommerce_info`,`financial_info`,`traffic_analytics`,`technical_info`,`apps_integrations`,`activity_signals`,`crm`,`data_metadata`. If omitted, all sections are returned.

Request Examples

# Get all data for a domain
curl -X GET "https://www.storecensus.com/api/v1/website/example-store.com" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json"

# Get data by lead_id (direct lookup)
curl -X GET "https://www.storecensus.com/api/v1/website/12345" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json"

# Get only specific sections
curl -X GET "https://www.storecensus.com/api/v1/website/example-store.com?sections=basic_info,contact_info,crm" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json"

# Get specific sections by lead_id
curl -X GET "https://www.storecensus.com/api/v1/website/12345?sections=basic_info,crm" \
  -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"
      }
    ]
  },
  "activity_signals": {
    "freshness": {
      "last_activity_at": "string",
      "last_app_event_at": "string",
      "last_email_found_at": "string",
      "last_product_update_at": "string",
      "last_technology_change_at": "string",
      "last_theme_publish_at": "string"
    },
    "growth": {
      "product_page_count": {
        "delta_7d": number,
        "delta_30d": number,
        "current": number
      },
      "variant_count": {
        "delta_7d": number,
        "delta_30d": number,
        "current": number
      },
      "average_product_price": {
        "delta_7d": number,
        "delta_30d": number
      },
      "traffic_visits": {
        "delta_7d": number,
        "delta_30d": number
      },
      "email": {
        "new_7d": number,
        "new_30d": number
      },
      "technology": {
        "delta_7d": number,
        "delta_30d": number,
        "current": number
      },
      "spend_shopify_apps": {
        "delta_7d": number,
        "delta_30d": number
      },
      "spend_technology": {
        "delta_7d": number,
        "delta_30d": number
      },
      "app_events": {
        "installs_7d": number,
        "installs_30d": number,
        "uninstalls_7d": number,
        "uninstalls_30d": number
      }
    },
    "events": {
      "theme_changed_7d": boolean,
      "app_installed": boolean,
      "app_uninstalled": boolean,
      "tech_installed": boolean,
      "tech_uninstalled": boolean,
      "products_changed": boolean,
      "emails_changed": boolean
    },
    "changes": {
      "YYYY-MM-DD": [
        {
          "change_type": "string",
          "entity_type": "string",
          "entity_id": "string",
          "old_value": "any",
          "new_value": "any"
        }
      ]
    }
  },
  "crm": {
    "lists": ["string"],
    "note": "string",
    "note_updated_at": "string",
    "rating": number,
    "status": "string",
    "has_reminder": boolean,
    "exported": boolean,
    "exported_time": "string",
    "is_following": boolean
  },
  "data_metadata": {
    "lead_id": "string",
    "last_updated": "string",
    "data_source": "string",
    "api_version": "string"
  }
}

The /stores Endpoint

Endpoint Details

URL	`POST /api/v1/stores`
Description	Retrieve filtered lists of Shopify stores with comprehensive data and cursor-based pagination
Authentication	Required (Bearer token)
Rate Limited	Yes (based on subscription plan)

Request Body Parameters

Parameter	Type	Description
`filters`	object	Filter criteria (country, vertical, apps, traffic, etc.)
`sort`	object	Sort configuration with column and direction
`pageSize`	number	Results per page (50-500, default: 50)
`cursor`	string	Pagination cursor from previous response
`sections`	array	Data sections to include (null = all sections)

Complete Filters Reference

The endpoint supports 100+ filter parameters. Below is the complete reference with types, descriptions, and examples:

Filter Parameter	Type	Description	Example
📍 Location Filters
`country`	string[]	Filter by country codes (ISO 3166-1 alpha-2)	`["US", "GB", "CA"]`
`state`	string[]	Filter by state abbreviations	`["CA", "NY", "TX"]`
🏢 Business Filters
`vertical`	string[]	Filter by business vertical/industry	`["Fashion", "Electronics"]`
`language`	string[]	Filter by website language	`["English", "Spanish"]`
`employees`	(number \| string)[]	Employee count range [min, max]	`[10, 100] or ["10", "100"]`
`websiteCreatedAt`	object	Date range: {enabled, startDate, endDate}	`{enabled: true, startDate: "2023-01-01", endDate: "2024-01-01"}`
`websiteUpdatedAt`	object	Last crawled date range	`{enabled: true, startDate: "2024-01-01"}`
`domainExtension`	string[]	Filter by domain extension	`[".com", ".co"]`
📧 Contact Filters
`contact`	string[]	Filter by contact availability (email, phone)	`["email"]`
`email_type`	string[]	Filter by email type	`["founder_personal"]`
🛍️ E-commerce Filters
`theme`	string[]	Filter by Shopify theme name	`["Dawn", "Debut"]`
`currency`	string[]	Filter by store currency	`["USD", "EUR"]`
`productPagesMin`	number \| string	Minimum number of product pages	`100 or "100"`
`productPagesMax`	number \| string	Maximum number of product pages	`1000 or "1000"`
`productVariantsMin`	number \| string	Minimum number of product variants	`500 or "500"`
`productVariantsMax`	number \| string	Maximum number of product variants	`5000 or "5000"`
`avgProductPriceMin`	number \| string	Minimum average product price	`50 or "50"`
`avgProductPriceMax`	number \| string	Maximum average product price	`200 or "200"`
💰 Financial Filters
`estimatedSales`	(number \| string)[]	Estimated monthly sales range [min, max]	`[5000, 10000] or ["5000", "10000"]`
`technologySpend`	(number \| string)[]	Technology spend range [min, max]	`[1000, 5000] or ["1000", "5000"]`
`estimatedVisits`	(number \| string)[]	Estimated monthly visits range [min, max]	`[5000, 100000] or ["5000", "100000"]`
📊 Traffic Filters
`totalTrafficMin`	number \| string	Minimum total monthly traffic	`10000 or "10000"`
`totalTrafficMax`	number \| string	Maximum total monthly traffic	`100000 or "100000"`
`organicTrafficMin`	number \| string	Minimum organic traffic	`5000 or "5000"`
`organicTrafficMax`	number \| string	Maximum organic traffic	`50000 or "50000"`
`paidTrafficMin`	number \| string	Minimum paid traffic	`1000 or "1000"`
`paidTrafficMax`	number \| string	Maximum paid traffic	`10000 or "10000"`
📱 App Filters
`apps`	number[] \| string[]	Filter by installed app IDs (integers or strings, converted to strings internally)	`[12345, 67890]`
`appSelectionMode`	object	Control app filter behavior per app ID: {"appId": "yes"\|"no"}. "yes" = has app installed (default), "no" = does NOT have app installed	`{"12345": "yes", "67890": "no"}`
`verifiedAppInstalls`	string[]	Filter for verified app installations only (use ["true"])	`["true"]`
`uninstalledAppsOnly`	string[]	Filter for uninstalled apps only (use ["true"])	`["true"]`
`installedDateFrom`	string	App installed start date (YYYY-MM-DD)	`"2024-01-01"`
`installedDateTo`	string	App installed end date (YYYY-MM-DD)	`"2024-12-31"`
`uninstalledDateFrom`	string	App uninstalled start date (YYYY-MM-DD)	`"2025-12-10"`
`uninstalledDateTo`	string	App uninstalled end date (YYYY-MM-DD)	`"2024-06-30"`
⚙️ Technology Filters
`trackingAnalytics`	string[]	Filter by tracking/analytics technologies	`["Google Analytics", "Facebook Pixel"]`
`trackingAnalyticsToggle`	object	Include/exclude: {tech: boolean}	`{"Google Analytics": true}`
♿ Accessibility Filters
`accessibility`	string[]	Accessibility metrics to filter by	`["performance", "seo"]`
`accessibilityToggle`	object	Enable metrics: {metric: boolean}	`{"performance": true}`
`accessibilityValues`	object	Threshold values: {metric: number}	`{"performance": 90}`
`accessibilityOperators`	object	Operators: {metric: "gte"\|"lte"\|"eq"}	`{"performance": "gte"}`
⚡ Activity Signals Filters
`activityDelta`	string	Time period: "7", "30", or "90" days	`"7"`
`activity_events_*`	boolean	Event filters (any, app_installed, app_uninstalled, tech_installed, tech_uninstalled, products_changed, emails_changed, theme_changed)	`true`
`activity_freshness_*`	object	Date filters: {preset: "last_7_days"} or {min, max}	`{preset: "last_7_days"}`
`activity_growth_*_delta_min`	number \| string	Minimum growth delta (product_page, variant, tech, average_price, shopify_app_spend, tech_spend, traffic, app_installs, app_uninstalls, email_new)	`10 or "10"`
`activity_growth_*_delta_max`	number \| string	Maximum growth delta (product_page, variant, tech, average_price, shopify_app_spend, tech_spend, traffic, app_installs, app_uninstalls, email_new)	`100 or "100"`
📋 CRM & Export Filters
`crm_status`	string[]	Filter by CRM status	`["qualified", "contacted"]`
`crm_lists`	string[]	Filter by CRM list membership	`["Hot Leads", "Follow Up"]`
`crm_has_note`	boolean	Filter stores with notes	`true`
`crm_ratings`	number[]	Filter by star ratings (1-5)	`[4, 5]`
`crm_has_reminder`	boolean	Filter stores with active reminders	`true`
`website_following`	boolean	Filter followed stores	`true`
`show_exported`	boolean	Show only exported stores	`true`
`exclude_exported`	boolean	Exclude exported stores	`true`
`exported_date_range`	object	Filter by export date: {enabled, startDate, endDate}	`{enabled: true, startDate: "2024-01-01"}`

Available Sections

Control which data sections are included in the response:

["basic_info", "contact_info", "location_info", "social_media", "ecommerce_info", "financial_info", "traffic_analytics", "technical_info", "apps_integrations", "activity_signals", "crm", "data_metadata"]

Request Example

curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "country": ["US", "GB"],
      "vertical": ["Fashion"],
      "apps": ["klaviyo"],
      "totalTrafficMin": "10000",
      "contact": ["email"]
    },
    "sort": {
      "column": "website_created_at",
      "direction": "desc"
    },
    "pageSize": 100,
    "sections": ["basic_info", "contact_info", "apps_integrations", "activity_signals"]
  }'

Response Format

{
  "data": [
    {
      "basic_info": { ... },
      "contact_info": { ... },
      "location_info": { ... },
      "social_media": { ... },
      "ecommerce_info": { ... },
      "financial_info": { ... },
      "traffic_analytics": { ... },
      "technical_info": { ... },
      "apps_integrations": { ... },
      "activity_signals": { ... },
      "crm": { ... },
      "data_metadata": { ... }
    }
  ],
  "pagination": {
    "pageSize": 100,
    "hasMore": true,
    "nextCursor": "eyJwaXRJZCI6IjQ2VG9BNUlCQ3dqRjFWX...",
    "total": 1250,
    "returned": 100
  },
  "filters": { ... },
  "sort": { ... },
  "sections": [ ... ]
}

Pagination

This endpoint uses cursor-based pagination for efficient traversal of large result sets:

First request: Omit the cursor parameter
Subsequent requests: Include the nextCursor from the previous response
When hasMore is false, you've reached the end
Cursors are valid for 5 minutes

// Next page request
curl -X POST "https://www.storecensus.com/api/v1/stores" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": { ... },
    "pageSize": 100,
    "cursor": "eyJwaXRJZCI6IjQ2VG9BNUlCQ3dqRjFWX..."
  }'

Best Practices

Use appropriate page sizes (50-100 for interactive use, up to 500 for bulk exports)
Request only needed sections using the sections parameter
Implement exponential backoff when receiving 429 rate limit responses
Store cursors to resume pagination if interrupted
Use specific filters to reduce result set size and improve performance

The /enrich Endpoint

Endpoint Details

URL	`POST /api/v1/enrich`
Description	Enrich lead data by retrieving contact information (emails and phone numbers) for specified lead_ids. Credits are only deducted for leads that have contact information available.
Authentication	Required (Bearer token)
Rate Limited	Yes (based on subscription plan)

💡 Smart Credit Usage: This endpoint only deducts credits for leads that contain contact information (at least one email or phone number). Leads without contact info are returned but don't consume credits, making this endpoint cost-effective for bulk enrichment.

Request Body Parameters

Parameter	Type	Description
`lead_ids`required	array of integers	Array of lead_ids to enrich. Maximum 1000 lead_ids per request. Each lead_id must be a positive integer.

Request Example

curl -X POST "https://www.storecensus.com/api/v1/enrich" \
  -H "Authorization: Bearer your.api.key" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_ids": [12345, 67890, 11223, 44556]
  }'

Response Format

{
  "success": true,
  "results": [
    {
      "lead_id": 12345,
      "domain": "example-store.com",
      "emails": [
        {
          "email": "contact@example-store.com",
          "email_type": "general",
          "validated": true,
          "found_date": "2024-01-15"
        },
        {
          "email": "support@example-store.com",
          "email_type": "support",
          "validated": true,
          "found_date": "2024-01-20"
        }
      ],
      "phone": "+1-555-123-4567; +1-555-987-6543",
      "has_contact_info": true
    },
    {
      "lead_id": 67890,
      "domain": "another-store.com",
      "emails": null,
      "phone": null,
      "has_contact_info": false
    }
  ],
  "summary": {
    "total_requested": 4,
    "stores_with_contact_info": 2,
    "stores_without_contact_info": 2,
    "credits_deducted": 2
  }
}

Response Fields

Field	Description
`success`	Boolean indicating if the request was successful
`results`	Array of enrichment results for each lead_id found
`results[].lead_id`	The lead ID
`results[].domain`	The store's domain name
`results[].emails`	Array of email objects or null if no emails found
`results[].phone`	Phone number(s) as semicolon-separated string, or null if no phones found
`results[].has_contact_info`	Boolean indicating if this lead has any contact information
`summary.total_requested`	Total number of lead_ids requested
`summary.stores_with_contact_info`	Number of stores that had contact information
`summary.stores_without_contact_info`	Number of stores without contact information
`summary.already_unlocked`	Number of stores that were already unlocked (no credit charged)
`summary.newly_unlocked`	Number of stores newly unlocked in this request
`summary.credits_deducted`	Number of credits deducted (1 per newly unlocked store only)
`credits.remaining`	Total credits remaining after this request
`credits.subscription`	Subscription credits remaining
`credits.addon`	Add-on credits remaining

Credit Deduction Logic

1 credit per lead is deducted only if the lead has at least one email OR one phone number
Already unlocked leads are FREE - if you've previously unlocked a lead, you can access it again without using credits
Leads without any contact information are returned but do not consume credits
The lead is automatically saved to your unlocked_contact_info table when contact info is retrieved for the first time
The response includes your remaining credit balance (credits.remaining) so you can track usage
If you don't have enough credits, the request will fail with a 402 status code before any data is returned

Error Responses

Status Code	Error	Description
400	lead_ids must be a non-empty array	The lead_ids parameter is missing or invalid
400	Maximum 1000 lead_ids per request	Too many lead_ids provided in a single request
402	Insufficient credits available	Not enough credits to complete the enrichment

StoreCensus API Documentation

Introduction

Authentication

Authentication Method

Authentication Errors

Rate Limits

Rate Limit Plans

Rate Limit Implementation

Error Handling

Error Response Format

The /website Endpoint

Endpoint Details

Path Parameters

Query Parameters

Request Examples

Response Format

The /stores Endpoint

Endpoint Details

Request Body Parameters

Complete Filters Reference

Available Sections

Request Example

Response Format

Pagination

Best Practices

The /enrich Endpoint

Endpoint Details

Request Body Parameters

Request Example

Response Format

Response Fields

Credit Deduction Logic

Error Responses

Subscription Required