Skip to main content

Crosstab

note

Your entitlements change which surveys and authorization groups you can call. A valid API key without access to the requested dataset returns 403 — see Authentication.

Getting started​

URL REQUEST (POST)
https://engines.api.telmar.com/omg/prd/v1/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.

Every request needs a Telmar-Engine-Authorizer API key.

Main parameters​

Survey and authorization group​

SurveyCode identifies the target survey dataset (e.g. "M20F"). AuthorizationGroup is an optional authorization group filter — use "_ALL_" to include all groups.

Survey and authorization group
{
  "SurveyCode": "M20F",
  "AuthorizationGroup": "_ALL_"
}

Population base​

PopulationBaseCode identifies the population base for the query (e.g. "AR18_24").

Population base
{
  "PopulationBaseCode": "AR18_24"
}

Target codes​

TargetCodes is an array of 1 or 2 target codes. Each entry produces one row in Results. Sending more than two codes returns 400.

Target codes
{
  "TargetCodes": ["OMEN", "OWOMEN"]
}

Let's go to examples​

Every payload below is synthetic. The shared constants they reuse — the survey, population base, authorizer and target codes — are documented once in the example gallery.

Basic crosstab for two targets, one population base​

POST/crosstab200 OKExample

The default call shape from the Explore API docs. Queries M20F with AR18_24 as the population base and returns results for OMEN (Men) and OWOMEN (Women).

note

`TargetCodes` accepts 1–2 members. Multiply `WgtAud` by `AudienceReportUnits` for the absolute projected audience. `Stbl` of `0` means stable; `1` means unstable (use with caution).

URL REQUEST (POST)
{
  "SurveyCode": "M20F",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": [
    "OMEN",
    "OWOMEN"
  ]
}
The same call as curl
curl -X POST 'https://engines.api.telmar.com/omg/prd/v1/crosstab' \
  -H 'Telmar-Engine-Authorizer: SAMPLE.ENGINE.AUTHORIZER' \
  -H 'Content-Type: application/json' \
  -d '{
  "SurveyCode": "M20F",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": [
    "OMEN",
    "OWOMEN"
  ]
}'
We will receive a json like this — 200 OK
{
  "ResultCode": 0,
  "ResultDescription": "",
  "Results": [
    {
      "Resps": 1000,
      "WgtAud": 10000,
      "Stbl": 0
    },
    {
      "Resps": 123,
      "WgtAud": 4444,
      "Stbl": 1
    }
  ],
  "AudienceReportUnits": 1000
}

Crosstab for a single target code​

POST/crosstab200 OKExample

Use when you only need one target against the population base — for example a single demographic cut on a dashboard tile.

note

`Results` always has one entry per target. With a single `TargetCodes` member the array length is 1.

URL REQUEST (POST)
{
  "SurveyCode": "M20F",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": [
    "OMEN"
  ]
}
The same call as curl
curl -X POST 'https://engines.api.telmar.com/omg/prd/v1/crosstab' \
  -H 'Telmar-Engine-Authorizer: SAMPLE.ENGINE.AUTHORIZER' \
  -H 'Content-Type: application/json' \
  -d '{
  "SurveyCode": "M20F",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": [
    "OMEN"
  ]
}'
We will receive a json like this — 200 OK
{
  "ResultCode": 0,
  "ResultDescription": "",
  "Results": [
    {
      "Resps": 1000,
      "WgtAud": 10000,
      "Stbl": 0
    }
  ],
  "AudienceReportUnits": 1000
}

More than two TargetCodes in one request​

POST/crosstab400 Bad RequestExample

This is the most common first failure. `TargetCodes` is capped at two members per call. Split larger universes across multiple requests.

note

Rejected requests are not billed. Fix the request and retry — retrying unchanged will fail identically.

URL REQUEST (POST)
{
  "SurveyCode": "M20F",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": [
    "OMEN",
    "OWOMEN",
    "OTEENS"
  ]
}
The same call as curl
curl -X POST 'https://engines.api.telmar.com/omg/prd/v1/crosstab' \
  -H 'Telmar-Engine-Authorizer: SAMPLE.ENGINE.AUTHORIZER' \
  -H 'Content-Type: application/json' \
  -d '{
  "SurveyCode": "M20F",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": [
    "OMEN",
    "OWOMEN",
    "OTEENS"
  ]
}'
We will receive a json like this — 400 Bad Request
{
  "ResultCode": 400,
  "ResultDescription": "TargetCodes must contain between 1 and 2 items.",
  "error": {
    "code": "invalid_target_codes",
    "message": "TargetCodes must contain between 1 and 2 items.",
    "field": "TargetCodes",
    "hint": "Split the request into multiple crosstab calls of at most two targets each."
  }
}

Missing or expired authorizer​

POST/crosstab401 UnauthorizedExample

Check against this when your integration worked yesterday and stopped today. A 401 means the API could not establish who you are — almost always a missing or expired `Telmar-Engine-Authorizer` value.

note

401 is about identity, 403 is about entitlement. Do not retry a 401 with the same authorizer value: fetch a fresh one from the Developer Portal first. Portal session cookies are not engine credentials and will always produce this error.

URL REQUEST (POST)
{
  "SurveyCode": "M20F",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": [
    "OMEN",
    "OWOMEN"
  ]
}
The same call as curl
curl -X POST 'https://engines.api.telmar.com/omg/prd/v1/crosstab' \
  -H 'Telmar-Engine-Authorizer: expired.SAMPLE.AUTHORIZER' \
  -H 'Content-Type: application/json' \
  -d '{
  "SurveyCode": "M20F",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": [
    "OMEN",
    "OWOMEN"
  ]
}'
We will receive a json like this — 401 Unauthorized
{
  "ResultCode": 401,
  "ResultDescription": "The Telmar-Engine-Authorizer header is missing, malformed or expired.",
  "error": {
    "code": "unauthorized",
    "message": "The Telmar-Engine-Authorizer header is missing, malformed or expired.",
    "hint": "Request a new engine authorizer value from the Developer Portal and retry. Portal session cookies are not accepted."
  }
}

Caller is not entitled to the requested survey​

POST/crosstab403 ForbiddenExample

You will hit this when the authorizer is valid but your agreement does not cover the survey or authorization group you requested.

note

This is a commercial boundary, not a bug. Confirm the survey code and authorization group with Sales — no code change will resolve a missing entitlement.

URL REQUEST (POST)
{
  "SurveyCode": "RESTRICTED_SURVEY",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": [
    "OMEN"
  ]
}
The same call as curl
curl -X POST 'https://engines.api.telmar.com/omg/prd/v1/crosstab' \
  -H 'Telmar-Engine-Authorizer: SAMPLE.ENGINE.AUTHORIZER' \
  -H 'Content-Type: application/json' \
  -d '{
  "SurveyCode": "RESTRICTED_SURVEY",
  "AuthorizationGroup": "_ALL_",
  "PopulationBaseCode": "AR18_24",
  "TargetCodes": [
    "OMEN"
  ]
}'
We will receive a json like this — 403 Forbidden
{
  "ResultCode": 403,
  "ResultDescription": "The caller is not entitled to survey RESTRICTED_SURVEY.",
  "error": {
    "code": "forbidden_survey",
    "message": "The caller is not entitled to survey RESTRICTED_SURVEY.",
    "field": "SurveyCode",
    "hint": "Contact Sales to add this survey to your agreement."
  }
}