GEO Analysis Query Parameter Guide

Getting started tip: pick the closest example in Section 4, copy it, then modify only your date range and business fields.

This document explains how to call:

Method: POST

Path: /v1/open-api/geo/analysis

Production URL: https://api.dageno.ai/business/api/v1/open-api/geo/analysis

1. Prerequisites

Include header x-api-key.

Use Content-Type: application/json.

Send body in the DSL structure shown below.

2. Request Body Structure

{
  "target": {
    "entity": "topic",
    "metrics": ["visibility", "citation"],
    "filters": {
      "dateRange": {
        "startAt": "2026-03-01T00:00:00.000Z",
        "endAt": "2026-03-28T00:00:00.000Z"
      }
    }
  },
  "analysis": {
    "type": "ranking",
    "ranking": {
      "orderBy": "visibility",
      "direction": "desc"
    }
  }
}

2.1 Quick Parameter Template

Copy this template and replace placeholders:

{
  "target": {
    "entity": "<brand|topic|platform>",
    "metrics": ["<metric_1>", "<metric_2_optional>"],
    "filters": {
      "dateRange": {
        "startAt": "<ISO_8601_UTC>",
        "endAt": "<ISO_8601_UTC>"
      }
    }
  },
  "analysis": {
    "type": "<summary|trend|ranking|distribution|correlation|matrix>",
    "ranking": {
      "orderBy": "<metric_key>",
      "direction": "<asc|desc>"
    },
    "matrix": {
      "rowDimension": "<brand|topic>"
    }
  }
}

Notes:

Remove analysis.ranking unless analysis.type = ranking.

Remove analysis.matrix unless analysis.type = matrix.

3. Field-by-field Reference

Field	Type	Required	Allowed values	Notes
`target.entity`	string	Yes	`brand`, `topic`, `platform`	Analysis target dimension
`target.metrics`	string[]	Yes	`visibility`, `position`, `sentiment`, `citation`, `ai_mention`	Must be non-empty
`target.filters.dateRange.startAt`	string (ISO 8601)	Yes	e.g. `2026-03-01T00:00:00.000Z`	UTC recommended
`target.filters.dateRange.endAt`	string (ISO 8601)	Yes	e.g. `2026-03-28T00:00:00.000Z`	UTC recommended
`analysis.type`	string	Yes	`summary`, `trend`, `ranking`, `distribution`, `correlation`, `matrix`	Core analysis mode
`analysis.ranking.orderBy`	string	Conditional	metric key above	Required when `analysis.type = ranking`; must exist in `target.metrics`
`analysis.ranking.direction`	string	Conditional	`asc`, `desc`	Required when `analysis.type = ranking`
`analysis.matrix.rowDimension`	string	Conditional	`brand`, `topic`	Required when `analysis.type = matrix`

4. Real-world Use Cases (Business-first Examples)

This section starts from real analyst questions and then maps to payloads.

4.0 Quick Mapping: Question -> analysis.type

Business question	Recommended `analysis.type`
"What is my current performance snapshot?"	`summary`
"How did metrics change over time?"	`trend`
"Who is top/bottom this month?"	`ranking`
"How is share split across groups?"	`distribution`
"Do two metrics move together?"	`correlation`
"How do platforms x topics/brands compare in one view?"	`matrix`

4.1 Scenario: Monthly topic snapshot for GEO review

Business question:
"For this month, which topics have stronger visibility and citation?"

Recommended payload:

{
  "target": {
    "entity": "topic",
    "metrics": ["visibility", "citation", "sentiment"],
    "filters": {
      "dateRange": {
        "startAt": "2026-03-01T00:00:00.000Z",
        "endAt": "2026-03-31T23:59:59.999Z"
      }
    }
  },
  "analysis": {
    "type": "summary"
  }
}

How to read results:

Use rows[].topic to identify the topic.

Compare visibility, citation, and sentiment in the same row for prioritization.

4.2 Scenario: Weekly brand trend monitoring

Business question:
"Is brand visibility improving week by week during campaign period?"

Recommended payload:

{
  "target": {
    "entity": "brand",
    "metrics": ["visibility", "sentiment"],
    "filters": {
      "dateRange": {
        "startAt": "2026-03-01T00:00:00.000Z",
        "endAt": "2026-03-31T23:59:59.999Z"
      }
    }
  },
  "analysis": {
    "type": "trend"
  }
}

How to read results:

rows[] are time-series points keyed by date.

Track if visibility trend and sentiment trend move in the same direction.

4.3 Scenario: Platform leaderboard for current month

Business question:
"Which AI platforms drive the strongest visibility this month?"

Recommended payload:

{
  "target": {
    "entity": "platform",
    "metrics": ["visibility", "citation"],
    "filters": {
      "dateRange": {
        "startAt": "2026-03-01T00:00:00.000Z",
        "endAt": "2026-03-31T23:59:59.999Z"
      }
    }
  },
  "analysis": {
    "type": "ranking",
    "ranking": {
      "orderBy": "visibility",
      "direction": "desc"
    }
  }
}

How to read results:

Top rows are leaders (descending by visibility).

Use citation as a secondary KPI to validate quality, not only exposure.

Business question:
"How is citation share distributed across topics?"

Recommended payload:

{
  "target": {
    "entity": "topic",
    "metrics": ["citation"],
    "filters": {
      "dateRange": {
        "startAt": "2026-03-01T00:00:00.000Z",
        "endAt": "2026-03-31T23:59:59.999Z"
      }
    }
  },
  "analysis": {
    "type": "distribution"
  }
}

How to read results:

Values are returned as percentage distribution for each topic group.

Find low-share but strategic topics for next content sprint.

4.5 Scenario: Check whether visibility and sentiment correlate

Business question:
"When visibility goes up, does sentiment also improve?"

Recommended payload:

{
  "target": {
    "entity": "brand",
    "metrics": ["visibility", "sentiment"],
    "filters": {
      "dateRange": {
        "startAt": "2026-03-01T00:00:00.000Z",
        "endAt": "2026-03-31T23:59:59.999Z"
      }
    }
  },
  "analysis": {
    "type": "correlation"
  }
}

How to read results:

Check rows[0].r (correlation coefficient).

r close to 1: strong positive relation; close to -1: strong inverse relation.

4.6 Scenario: Platform x Topic matrix for channel strategy

Business question:
"Which platforms perform best for each topic cluster?"

Recommended payload:

{
  "target": {
    "entity": "platform",
    "metrics": ["citation"],
    "filters": {
      "dateRange": {
        "startAt": "2026-03-01T00:00:00.000Z",
        "endAt": "2026-03-31T23:59:59.999Z"
      }
    }
  },
  "analysis": {
    "type": "matrix",
    "matrix": {
      "rowDimension": "topic"
    }
  }
}

How to read results:

Each row represents one topic; each platform column contains metric values.

Use this matrix to decide platform-topic resource allocation.

5. cURL Example

6. Response Shape

Successful responses from executeDsl use the common wrapper:

{
  "success": true,
  "code": 0,
  "message": "OK",
  "data": {
    "rows": [],
    "query": {}
  }
}

Notes:

data.rows schema varies by analysis.type.

data.query echoes the original request body.

7. Common Errors and Fixes

Error message	Why it happens	How to fix
`metrics required`	`target.metrics` is missing or empty	Provide at least one metric
`ranking.orderBy must be included in metrics`	`orderBy` not present in `target.metrics`	Add `orderBy` metric to `target.metrics`
`correlation requires exactly 2 metrics`	Correlation received non-2 metrics	Send exactly 2 metrics
`distribution requires exactly 1 metric`	Distribution received non-1 metric	Send exactly 1 metric
`matrix requires entity: platform`	Matrix entity is not `platform`	Set `target.entity` to `platform`
`matrix requires analysis.matrix.rowDimension (brand or topic)`	Missing `rowDimension`	Add `analysis.matrix.rowDimension`
`ai_mention is not supported for matrix analysis`	Matrix metric is `ai_mention`	Use another metric

8. Quick Checklist Before Sending

target.entity is valid.

target.metrics is non-empty and compatible with analysis.type.

Date range is valid ISO 8601.

Ranking/matrix extra fields are present when required.

x-api-key is provided.

GEO Analysis Query Parameter Guide

1. Prerequisites#

2. Request Body Structure#

2.1 Quick Parameter Template#

3. Field-by-field Reference#

4. Real-world Use Cases (Business-first Examples)#

4.0 Quick Mapping: Question -> analysis.type#

4.1 Scenario: Monthly topic snapshot for GEO review#

4.2 Scenario: Weekly brand trend monitoring#

4.3 Scenario: Platform leaderboard for current month#

4.4 Scenario: Citation share by topic (content planning)#

4.5 Scenario: Check whether visibility and sentiment correlate#

4.6 Scenario: Platform x Topic matrix for channel strategy#

5. cURL Example#

6. Response Shape#

7. Common Errors and Fixes#

8. Quick Checklist Before Sending#

1. Prerequisites

2. Request Body Structure

2.1 Quick Parameter Template

3. Field-by-field Reference

4. Real-world Use Cases (Business-first Examples)

4.0 Quick Mapping: Question -> analysis.type

4.1 Scenario: Monthly topic snapshot for GEO review

4.2 Scenario: Weekly brand trend monitoring

4.3 Scenario: Platform leaderboard for current month

4.4 Scenario: Citation share by topic (content planning)

4.5 Scenario: Check whether visibility and sentiment correlate

4.6 Scenario: Platform x Topic matrix for channel strategy

5. cURL Example

6. Response Shape

7. Common Errors and Fixes

8. Quick Checklist Before Sending