Skip to main content

Aggregations

GET/api/v1/search/aggregations

Overview​

Returns aggregated statistics from your indexed data for building dashboards and analytics views.

Use cases: Dashboard statistics, data overview, trend analysis, filter counts.

Authentication​

Authorizationstringrequired

Bearer token in format: Bearer client_id:api_key:api_secret

Query Parameters​

job_typestring

Filter aggregations by job type (e.g., spiderMaps, spiderSite).

Response​

successboolean

Whether the request was successful.

total_documentsinteger

Total number of indexed documents.

by_job_typearray

Document counts by job type.

by_categoryarray

Document counts by category.

by_countryarray

Document counts by country.

avg_ratingnumber

Average rating across all businesses.

total_reviewsinteger

Total review count across all businesses.

verified_emails_countinteger

Number of verified email addresses.

indexed_over_timearray

Indexing trend over time for charts.

errorstring

Error message if any.

Examples​

Request Example

curl -X GET "https://spideriq.ai/api/v1/search/aggregations" \
  -H "Authorization: Bearer cli_xxx:key:secret"
curl -X GET "https://spideriq.ai/api/v1/search/aggregations?job_type=spiderMaps" \
  -H "Authorization: Bearer cli_xxx:key:secret"

Response Example

{
  "success": true,
  "total_documents": 32798,
  "by_job_type": [
    {"name": "spiderMaps", "count": 28500},
    {"name": "spiderSite", "count": 4298}
  ],
  "by_category": [
    {"name": "Restaurant", "count": 8234},
    {"name": "Coffee Shop", "count": 3421},
    {"name": "Hotel", "count": 2156},
    {"name": "Retail", "count": 1987}
  ],
  "by_country": [
    {"name": "Luxembourg", "count": 15234},
    {"name": "Germany", "count": 8456},
    {"name": "France", "count": 5678}
  ],
  "avg_rating": 4.2,
  "total_reviews": 456789,
  "verified_emails_count": 12456,
  "indexed_over_time": [
    {"date": "2026-01-15", "count": 1234},
    {"date": "2026-01-16", "count": 1567},
    {"date": "2026-01-17", "count": 1890},
    {"date": "2026-01-18", "count": 2134},
    {"date": "2026-01-19", "count": 1756},
    {"date": "2026-01-20", "count": 2345},
    {"date": "2026-01-21", "count": 1876}
  ]
}

Dashboard Example​

Here's how to use aggregations to build a dashboard:

async function loadDashboardStats(authToken) {
  const response = await fetch(
    'https://spideriq.ai/api/v1/search/aggregations',
    { headers: { 'Authorization': `Bearer ${authToken}` } }
  );
  const data = await response.json();

  return {
    totalRecords: data.total_documents,
    avgRating: data.avg_rating?.toFixed(1),
    verifiedEmails: data.verified_emails_count,
    jobTypeBreakdown: data.by_job_type,
    topCategories: data.by_category.slice(0, 5),
    indexingTrend: data.indexed_over_time
  };
}