Endpoint reference

This page is the normative reference for the Explore / Crosstab API (OAS3). It tracks the OpenAPI document, which is the machine-readable source of truth — the examples on this site are validated against it at build time.

Working from the spec

Point your generator at /openapi/sample-api.yaml (or GET /docs) to produce a typed client rather than hand-writing request models. The operationId values below are the names your generator will use.

Server

Base URL	https://engines.api.telmar.com/omg/prd/v1
Media type	application/json
Auth	Telmar-Engine-Authorizer: <api-key>

All endpoints below are relative to the base URL.

Operations

| Method | Path | Description | Auth | Billed | | --- | --- | --- | --- | | GET | /docs | Returns the OpenAPI specification for this service in JSON format | Not required | No | | POST | /crosstab | Executes a crosstab query against the dataset and returns weighted audience results | Required | Yes, on success | | OPTIONS | /crosstab | CORS preflight check for the /crosstab endpoint | Not required | No |

operationId	Method and path
docs	GET /docs
crosstab	POST /crosstab
crosstabOptions	OPTIONS /crosstab

---

GET /docs

Returns the full OpenAPI specification for this service as a JSON object. Useful for programmatic discovery of the API schema. No authentication is required.

Parameters

None.

Response — 200 OK

Field	Type	Description
(body)	object	The OpenAPI specification document in application/json format

---

POST /crosstab

Executes a crosstab query against a specified survey dataset. Returns weighted audience counts, unweighted respondent counts, and stability indicators for each requested target code.

Request

Content-Type	application/json
Body	CrosstabRequest (required)

Request schema — CrosstabRequest

Field	Type	Required	Description
SurveyCode	string	Yes	Identifies the target survey dataset (e.g. "M20F")
AuthorizationGroup	string	No	Authorization group filter. Use "_ALL_" to include all groups
PopulationBaseCode	string	Yes	Population base for the query (e.g. "AR18_24")
TargetCodes	string[]	Yes	Target segment codes. Min 1 item, max 2 items

Request example

{
  "SurveyCode": "M20F",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": ["OMEN", "OWOMEN"]
}

This example queries the M20F survey using AR18_24 as the population base, and returns results for two target segments: OMEN (Men) and OWOMEN (Women).

Response schema — CrosstabResponse

Field	Type	Description
ResultCode	integer	Numeric status code. 0 indicates success
ResultDescription	string	Human-readable description of the result status
Results	CrosstabResult[]	One result object per TargetCode. Min 1, max 2
AudienceReportUnits	integer	Audience unit multiplier applied to weighted counts (e.g. 1000)

Result object — CrosstabResult

Field	Type	Description
WgtAud	number (float)	Weighted projected audience size. Multiply by AudienceReportUnits for the absolute figure
Resps	integer	Un-weighted count of respondents matching this target code
Stbl	integer (0 | 1)	Stability factor. 0 = Stable, 1 = Unstable. Unstable results indicate low respondent counts and should be used with caution

Response example — 200 OK

{
  "ResultCode": 0,
  "ResultDescription": "",
  "Results": [
    { "Resps": 1000, "WgtAud": 10000, "Stbl": 0 },
    { "Resps": 123, "WgtAud": 4444, "Stbl": 1 }
  ],
  "AudienceReportUnits": 1000
}

Response headers

Header	Type
Access-Control-Allow-Origin	string

---

OPTIONS /crosstab

CORS preflight endpoint for the /crosstab path. Browsers issue this automatically before cross-origin POST requests. No parameters required.

Response — 200 OK

Header	Type
Access-Control-Allow-Origin	string
Access-Control-Allow-Methods	string
Access-Control-Allow-Headers	string

---

Error codes

The API uses standard HTTP status codes. The ResultCode field in the response body provides additional detail.

HTTP code	ResultCode	Meaning
200	0	Success. Results returned normally
200	> 0	Partial or conditional result. Check ResultDescription
400	—	Bad request. Malformed JSON or missing required fields
401	—	Unauthorized. Verify API key or Cognito credentials
403	—	Forbidden. User does not have access to the requested dataset
500	—	Internal server error. Contact TelmarHelixa support

Limits

Limit	Value
Target codes per request	1–2
Result shape	1 column × up to 2 rows (or 2 columns × 1 row)
Maximum rows per axis	5,000 (may be adapted in future versions)
Surveys per request	1
Population bases per request	1

Commercial terms — volume commitments, contracted throughput and pricing — are part of your agreement and are not published here. Contact Sales.

Contact Sales

Request access

Open in Developer Portal ↗Authentication docs ↗