---
title: "Get location reports (v2)"
method: GET
path: "/api/v1/discovery/location-reports-v2/{id}"
tags: ["discovery"]
---

# Get location reports (v2)

`GET /api/v1/discovery/location-reports-v2/{id}`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/discovery/location-reports-v2/{id}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

Read a campaign's Locations report over the conversations dated in the 30 days ending its results window's as-of day (`scope.window`): its customers rolled up country → region → city → postcode, with each place's brand share and win rate and their change since 30 days before the as-of day, its win and loss reasons, and revenue influence, under an optional brand lens and segments. Pass drivers=false or revenue=false to skip those reads.

## Path parameters

- `id` string, uuid, required: Discovery campaign id.

## Query parameters

- `dateRange` string, nullable: Result window: `all`, a preset id, or `yyyy-MM-dd..yyyy-MM-dd`. Omit for the campaign's default window.
- `brandPerspective` string, nullable: Read the results as this brand (one of the campaign's brands). Omit for your own.
- `segments` string[]: Narrows the read to these segments, ANDed: one `axis:id` per axis (any number of distinct `customer:` entries), in canonical axis order. Empty reads the whole dispatch.
- `drivers` boolean: Read each place's win and loss reasons. Default true; false leaves `drivers` empty.
- `revenue` boolean: Read revenue influence. Default true; it is read only under the campaign's own brand.

## Headers

- `Point11-Organization` string, uuid

## Response `200`

Success.

- DiscoveryLocationReportsGetV2Response
  - `scope` DiscoveryScope, required
    - `campaignId` string, required
    - `state` 'ready' | 'running' | 'failed' | 'out-of-range' | 'no-campaign', required: `ready` carries results; every other state carries none.
    - `failureReason` string, nullable, required
    - `perspective` object, nullable, required: The brand lens applied; null when the report honors no lens or carries no results.
      - `brand` string, required: The brand the results were read as.
      - `isOwnBrand` boolean, required: Whether that brand is the campaign's own.
    - `window` object, nullable, required: The results window; null unless `state` is `ready`.
      - `from` string, date, required: The first UTC day a trend plots: the range's, never before the first interaction.
      - `to` string, date, required: The last UTC day a trend plots: the range's end, never past today.
      - `asOf` string, date, required: The UTC day every single value is as of: its value is the average over the campaign's interactions dated in the 30 days ending with it. The range's end, or, when those 30 days hold none, the last day with an interaction.
      - `comparedTo` string, date, required: The day a change compares with: 30 days before asOf.
      - `interactionCount` integer, required: The interactions dated in the 30 days ending asOf, under the scope.
      - `customerCount` integer, required: The distinct customers of those interactions.
  - `report` object, nullable, required: Every value as of the results window's as-of day.
    - `locations` object[], required: Places in tree order: each parent before its children.
      - `id` string, required
      - `type` 'country' | 'admin1' | 'city' | 'postcode', required
      - `name` string, required
      - `shortName` string, required
      - `color` string, required
      - `parentId` string, nullable, required
      - `childIds` string[], required
      - `level` 1 | 2 | 3 | 4, required: 1 country → 4 postcode.
      - `countryCode` string, nullable, required
      - `admin1Code` string, nullable, required
      - `city` string, nullable, required
      - `postcode` string, nullable, required
      - `map` union, required: How a map draws the place: a boundary region, a point, or not at all.
        - object
          - `mode` 'region', required
          - `regionCode` string, required
          - `resolution` 'countries' | 'provinces' | 'postal', required
        - object
          - `mode` 'marker', required
          - `latitude` number, required
          - `longitude` number, required
          - `regionCode` string
          - `resolution` 'countries' | 'provinces' | 'postal'
        - object
          - `mode` 'none', required
      - `totalConversations` number, required: The as-of window's conversations of the place's customers.
      - `mentioned` number, required: Conversations that mentioned the brand.
      - `won` number, required: Conversations the brand won.
      - `brandShare` number, required
      - `winRate` number, required
      - `vsPortfolioPts` number, required: Brand win rate minus the campaign's all-up brand win rate, in points.
      - `topCompetitor` string, nullable
      - `isHomeBase` boolean
      - `geoRegion` string, nullable
      - `geoResolution` 'countries' | 'provinces' | 'postal', nullable
      - `revenueInfluencedUsd` number, nullable: Target revenue influenced; null when revenue was not read.
      - `brandShareDelta` number, nullable, required: The value minus its value in the window that ends 30 days before the as-of day, in points; null when that window holds none of the place's conversations.
      - `winRateDelta` number, nullable, required: The value minus its value in the window that ends 30 days before the as-of day, in points; null when that window holds none of the place's conversations.
    - `drivers` object[], required
      - `locationId` string, required
      - `kind` 'win' | 'loss', required
      - `label` string, required: The reason, as the model wrote it.
      - `count` number, required: The as-of window's conversations that gave it.
    - `conversationCount` number, required: The as-of window's conversations in scope.
    - `portfolioShare` number, required
    - `portfolioWinRate` number, required
    - `revenueCoverage` object, required
      - `scope` 'locations': Location estimates may overlap markets.
      - `status` 'none' | 'partial' | 'complete', required
      - `includedLineCount` number, required
      - `totalLineCount` number, required
      - `coveredConversationCount` number, required
      - `totalConversationCount` number, required
      - `coveragePct` number, required

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

[API](https://skmtc.dev/point11/apis/point11-api.md) · [All operations](https://skmtc.dev/point11/apis/point11-api/llms.txt) · [OpenAPI document](https://skmtc.dev/point11/apis/point11-api/revisions/5241805fe425?raw)