Delivery architecture
One logical data model is available through the REST API or Data Warehouse delivery.
Each delivery surface preserves the same company and metric identifiers, taxonomy semantics, classifier versions, lineage fields, and null behavior.
REST API
Read-only, fact-oriented resources for applications, notebooks, and scheduled ingestion.
Data Warehouse
Equivalent typed tables distributed through Snowflake or BigQuery for institutional research pipelines.
No raw job titles, descriptions, URLs, or posting identifiers are part of the published Job Postings contract. KPI observations expose source-check lineage rather than duplicating underlying filing text.
REST conventions
GET-only API conventions rooted at https://api.softwareiq.io/v1.
/v1/{resource}Read a paginated collection. Available filters are resource-specific and use exact canonical identifiers unless stated otherwise.
| Parameter | Required | Behavior |
|---|---|---|
| page_size | No | Requested page size, subject to the service maximum. |
| cursor | No | Opaque continuation token from meta.next_cursor; do not parse or construct it. |
- Authenticate with
Authorization: Bearer <token>. - Dates and timestamps use ISO 8601; timestamps include an offset.
- Decimals are JSON strings so clients do not silently lose precision.
- Pagination order is deterministic for each endpoint. A cursor is scoped to the original resource and filter set.
- Null means unavailable, not applicable, or not observed as defined by the field. It must not be coerced to zero.
curl --get 'https://api.softwareiq.io/v1/kpi-facts' \
--header 'Authorization: Bearer $SOFTWAREIQ_TOKEN' \
--data-urlencode 'company_id=siqco:example' \
--data-urlencode 'page_size=100'
{
"data": [{ "company_id": "siqco:example", "value": "1582000000.000000000000" }],
"meta": { "next_cursor": "eyJwYWdlIjoyfQ", "has_more": true }
}{
"error": {
"code": "invalid_parameter",
"message": "period_start must be an ISO 8601 date",
"request_id": "req_01J..."
}
}Resource catalog
Fact-oriented endpoints keep observations separate from the dictionaries and versions needed to interpret them.
| Resource | Area | Purpose |
|---|---|---|
| /companies | Shared | Stable company identifiers and current coverage metadata. |
| /datasets | Shared | Dataset freshness and active classification metadata. |
| /metric-definitions | KPI | Canonical metric labels, formats, and source-key mappings. |
| /kpi-facts | KPI | Current annual and quarterly standardized KPI observations. |
| /guidance-facts | KPI | Normalized management guidance and outcome comparisons. |
| /job-postings/daily | Jobs | Daily observed totals and complete classified intersections. |
| /job-postings/weekly | Jobs | Weekly observations with collection and comparability state. |
| /job-taxonomy-members | Jobs | Versioned dimension labels and hierarchy. |
| /classifier-versions | Jobs | Classifier, taxonomy, and rule-set compatibility tuples. |
| /job-collection-events | Jobs | ATS migrations, gaps, and other continuity events. |
Use company_id, not ticker or display name, as the durable company join. Use metric_id for normalized KPI work and taxonomy member IDs for job dimensions. Metadata resources are first-class inputs to a reproducible research extract.
Data Warehouse model
Snowflake and BigQuery distributions expose the same logical tables and analytical grain.
Warehouse tables use snake-case field names aligned with the REST resources. Identifiers, joins, field definitions, and null semantics remain consistent across delivery platforms; physical data types are mapped to the corresponding Snowflake or BigQuery type.
Controls for institutional research
Availability, versioning, and lineage are part of the dataset—not implementation details to discard.
Archive dated extracts when a strategy requires an as-known-at-the-time research panel.
Pin job classification versions in research artifacts. The catalog active version is convenient for current analysis, but can change as methods improve.
Use availability, continuity, comparability, and collection-event fields before calculating deltas. An ATS migration creates a new baseline rather than artificial hiring.
Retain KPI source-check identifiers and definition metadata. Standardization improves comparability but does not erase company-specific disclosure context.