REST API

https://your-instance.com/api/v1

GET /api/v1/events

{
  events: [
    {
      id: number,
      dataset: {
        id: number,
        title: string,
        catalog: string
      },
      data: Record<string, unknown>,  // Event-specific data
      location: {
        longitude: number,
        latitude: number
      } | null,
      eventTimestamp: string,
      isValid: boolean
    }
  ],
  pagination: {
    page: number,
    limit: number,
    totalDocs: number,
    totalPages: number,
    hasNextPage: boolean,
    hasPrevPage: boolean,
    nextPage: number | null,
    prevPage: number | null
  }
}

curl "https://your-instance.com/api/v1/events?\
catalog=tech-events&\
startDate=2024-01-01&\
endDate=2024-12-31&\
page=1&\
limit=100"

GET /api/v1/events/geo

{
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      geometry: {
        type: "Point",
        coordinates: [longitude, latitude]
      },
      properties: {
        id: number | string,
        type: "event-cluster" | "event-point",
        count?: number,              // For clusters only
        title?: string,              // For individual events
        eventIds?: number[]          // For small clusters (≤10 events)
      }
    }
  ]
}

curl "https://your-instance.com/api/v1/events/geo?\
bounds=%7B%22north%22%3A37.8%2C%22south%22%3A37.7%2C%22east%22%3A-122.3%2C%22west%22%3A-122.5%7D&\
zoom=12&\
catalog=sf-events"

GET /api/v1/events/temporal

{
  histogram: [
    {
      date: string,        // Bucket start (ISO 8601)
      dateEnd: string,     // Bucket end (ISO 8601)
      count: number        // Events in this bucket
    }
  ],
  metadata: {
    total: number,
    dateRange: {
      min: string | null,
      max: string | null
    },
    counts: {
      datasets: number,
      catalogs: number
    },
    topDatasets: string[],
    topCatalogs: string[]
  }
}

curl "https://your-instance.com/api/v1/events/temporal?\
catalog=tech-events&\
startDate=2024-01-01&\
endDate=2024-12-31"

GET /api/v1/events/stats

{
  items: [
    {
      id: number | string,
      name: string,
      count: number
    }
  ],
  total: number,
  groupedBy: "catalog" | "dataset"
}

curl "https://your-instance.com/api/v1/events/stats?\
groupBy=dataset&\
catalog=tech-events"

GET /api/v1/events/geo/stats

{
  p20: number,   // 20th percentile cluster size
  p40: number,   // 40th percentile
  p60: number,   // 60th percentile
  p80: number,   // 80th percentile
  p100: number   // Maximum cluster size
}

curl "https://your-instance.com/api/v1/events/geo/stats?\
catalog=tech-events"

GET /api/v1/sources/stats

{
  catalogCounts: Record<string, number>,   // catalog ID → event count
  datasetCounts: Record<string, number>,   // dataset ID → event count
  totalEvents: number
}

curl "https://your-instance.com/api/v1/sources/stats"

GET /api/import/:importId/progress

{
  type: "import-file",
  id: string | number,
  status: string,
  originalName: string,
  datasetsCount: number,
  datasetsProcessed: number,
  overallProgress: number,    // 0-100
  jobs: [
    {
      id: string | number,
      datasetId: string | number,
      datasetName?: string,
      stage: string,
      progress: number,         // 0-100
      rowsTotal: number,
      rowsProcessed: number,
      batchNumber: number,
      errors: number,
      duplicates: {
        internal: number,
        external: number
      },
      schemaValidation?: {...},
      geocodingProgress?: {...},
      results?: {...}
    }
  ],
  errorLog?: string[],
  completedAt?: string,
  createdAt: string
}

curl "https://your-instance.com/api/import/123/progress"

GET /api/quotas

{
  user: {
    id: string | number,
    email: string,
    role: "admin" | "user",
    trustLevel: "0" | "1" | "2" | "3" | "4" | "5"
  },
  quotas: {
    fileUploadsPerDay: {
      used: number,
      limit: number,
      remaining: number,
      allowed: boolean,
      resetTime: string,
      description: "Maximum file uploads allowed per day"
    },
    urlFetchesPerDay: {...},
    importJobsPerDay: {...},
    activeSchedules: {...},
    totalEvents: {...},
    eventsPerImport: {...},
    maxFileSizeMB: {
      limit: number,
      description: "Maximum file size in megabytes"
    }
  },
  summary: {
    hasUnlimitedAccess: boolean,
    nextResetTime: string
  }
}

X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: <remaining>
X-RateLimit-Reset: <ISO 8601 timestamp>

curl -H "Cookie: payload-token=..." \
  "https://your-instance.com/api/quotas"

GET /api/health

{
  database: {
    status: "ok" | "error",
    message?: string
  },
  migrations: {
    status: "ok" | "pending" | "error",
    pending?: string[]
  },
  postgis: {
    status: "ok" | "not found" | "error",
    version?: string
  },
  environment: {
    status: "ok" | "error",
    missing?: string[]
  }
}

curl "https://your-instance.com/api/health"

{
  error: string,           // Error type
  message?: string,        // Human-readable message
  details?: string,        // Additional error details
  code?: string           // Error code (e.g., "MISSING_DB_FUNCTION")
}

{
  success: false,
  error: "Rate limit exceeded",
  message: "Too many requests. Please wait 10 seconds.",
  limitType: "burst" | "hourly" | "daily",
  retryAfter: string  // ISO 8601 timestamp
}

Retry-After: <seconds>
X-RateLimit-Limit: <limit>
X-RateLimit-Remaining: 0
X-RateLimit-Reset: <timestamp>

Catalogs (top-level organization)
  └── Datasets (groupings within catalogs)
        └── Events (individual time-based data points)

{
  pagination: {
    page: number,
    limit: number,
    totalDocs: number,
    totalPages: number,
    hasNextPage: boolean,
    hasPrevPage: boolean,
    nextPage: number | null,
    prevPage: number | null
  }
}

const response = await fetch(
  "https://your-instance.com/api/v1/events?" +
    new URLSearchParams({
      bounds: JSON.stringify({
        north: 37.8,
        south: 37.7,
        east: -122.3,
        west: -122.5,
      }),
      startDate: "2024-01-01",
      endDate: "2024-12-31",
      limit: "100",
    })
);
 
const { events, pagination } = await response.json();

const response = await fetch(
  "https://your-instance.com/api/v1/events/geo?" +
    new URLSearchParams({
      bounds: JSON.stringify({
        north: 37.8,
        south: 37.7,
        east: -122.3,
        west: -122.5,
      }),
      zoom: "12",
      catalog: "tech-events",
    })
);
 
const geojson = await response.json();
// Use with MapLibre, Leaflet, etc.

async function pollImportProgress(importId: string) {
  const response = await fetch(`https://your-instance.com/api/import/${importId}/progress`);
 
  const progress = await response.json();
 
  console.log(`Overall: ${progress.overallProgress}%`);
  progress.jobs.forEach((job) => {
    console.log(`${job.datasetName}: ${job.stage} (${job.progress}%)`);
  });
 
  return progress;
}

const response = await fetch(
  "https://your-instance.com/api/v1/events/temporal?" +
    new URLSearchParams({
      catalog: "my-catalog",
      startDate: "2024-01-01",
      endDate: "2024-12-31",
    })
);
 
const { histogram, metadata } = await response.json();
 
// histogram = [{ date: 1704067200000, dateEnd: 1706745600000, count: 150 }, ...]
console.log(`Total events: ${metadata.total}`);