GET /v1/brands/{brand_id}/locations/{location_id}/geo-scan-comparisons

Compare two scans of a place

Two completed scans of the place side by side, the older one first: the change in mean rank (positive is worse), share of top 3 points and points found, and, when both used the same grid around the same centre, each point's rank in both. When both scans' runs have a completed AI grid, ai compares them the same way (the share of answers naming the brand, overall and point by point); ai_grids names each run's AI grid and its share either way, null for a run without one.

Path parameters

location_id string required

The place's id, from GET /v1/brands/{brand_id}/locations.
brand_id string required

Brand UUID.

Query parameters

from_scan_id string required

One scan's id.
to_scan_id string required

The other scan's id.
dry_run boolean optional

Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

default: false

Responses

Compare two scans of a place application/json

Type: GeoScanComparison

from_scan PlaceGeoScanSummary required

A scan of a place without its points.
Show fields

Type: PlaceGeoScanSummary
- grid_size integer required
- id string required
- keyword string required
- location_id string required
  
  The place the grid is centred on.
- point_count integer required
- spacing_km number required
- status enum required
  
  pending, running, completed or failed.
- avg_rank number (nullable) nullable
  
  Mean rank over the points it ranked at, once completed.
- center_lat number (nullable) nullable
- center_lng number (nullable) nullable
- completed_at string (nullable) nullable
- created_at string (nullable) nullable
- found_count integer (nullable) nullable
  
  Points where it is in the local pack, once completed.
- gbp_location_id string (nullable) nullable
  
  The Google location the place is linked to; null when it is not linked.
- last_error_message string (nullable) nullable
- object string
  
  Always geo_scan.
  
  default: `geo_scan`
- run_id string (nullable) nullable
  
  Scans started together share it.
- schedule_id string (nullable) nullable
  
  The schedule that ran it; null for a scan by hand.
- top3_count integer (nullable) nullable
  
  Points where it ranked 1 to 3, once completed.
same_grid boolean required

Both used the same grid around the same centre, so cells pairs each point.
to_scan PlaceGeoScanSummary required

A scan of a place without its points.
Show fields

Type: PlaceGeoScanSummary
- grid_size integer required
- id string required
- keyword string required
- location_id string required
  
  The place the grid is centred on.
- point_count integer required
- spacing_km number required
- status enum required
  
  pending, running, completed or failed.
- avg_rank number (nullable) nullable
  
  Mean rank over the points it ranked at, once completed.
- center_lat number (nullable) nullable
- center_lng number (nullable) nullable
- completed_at string (nullable) nullable
- created_at string (nullable) nullable
- found_count integer (nullable) nullable
  
  Points where it is in the local pack, once completed.
- gbp_location_id string (nullable) nullable
  
  The Google location the place is linked to; null when it is not linked.
- last_error_message string (nullable) nullable
- object string
  
  Always geo_scan.
  
  default: `geo_scan`
- run_id string (nullable) nullable
  
  Scans started together share it.
- schedule_id string (nullable) nullable
  
  The schedule that ran it; null for a scan by hand.
- top3_count integer (nullable) nullable
  
  Points where it ranked 1 to 3, once completed.
ai GeoScanAiComparison (nullable) nullable

Both scans' runs had a completed AI grid: its change; null otherwise.
ai_grids GeoScanAiGrids

Each scan's run's AI grid and its visibility, so a run with one shows even when the other has none.
Show fields

Type: GeoScanAiGrids
- from_scan_id string (nullable) nullable
  
  The older scan's run's AI grid.
- from_visibility_pct number (nullable) nullable
- to_scan_id string (nullable) nullable
  
  The newer scan's run's AI grid.
- to_visibility_pct number (nullable) nullable
avg_rank_change number (nullable) nullable

Positive is worse (a higher rank number).
cells array of GeoScanComparisonCell
found_change integer (nullable) nullable
object string

Always geo_scan_comparison.

default: `geo_scan_comparison`
top3_share_change number (nullable) nullable

Percentage points; negative is a drop.

Request validation failed application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Missing or invalid credentials application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

You do not have permission to access this resource application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource not found application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Resource conflict application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Per-minute rate limit exceeded application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

An unexpected error occurred application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Service temporarily unavailable, please retry application/json

Type: ApiError

error object required
Show fields
- code string required
  
  Stable machine-readable error code from the catalog.
- message string required
  
  Human-readable description suitable for logging.
- details object
  
  Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.
  
  Show fields
  
  Empty object (no properties).
request_id string

Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

format: `uuid`

Example response

{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}

Request example

curl --request GET \
  --url 'https://api.rankprompt.com/v1/brands/your_brand_id_here/locations/your_location_id_here/geo-scan-comparisons?from_scan_id=your_from_scan_id_here&to_scan_id=your_to_scan_id_here&dry_run=false' \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>'

const fetch = require('node-fetch');

const url = 'https://api.rankprompt.com/v1/brands/your_brand_id_here/locations/your_location_id_here/geo-scan-comparisons?from_scan_id=your_from_scan_id_here&to_scan_id=your_to_scan_id_here&dry_run=false';
const options = {method: 'GET', headers: {Authorization: 'Bearer rp_live_<YOUR_API_KEY>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

import requests

url = "https://api.rankprompt.com/v1/brands/your_brand_id_here/locations/your_location_id_here/geo-scan-comparisons"

querystring = {"from_scan_id":"your_from_scan_id_here","to_scan_id":"your_to_scan_id_here","dry_run":"false"}

headers = {"Authorization": "Bearer rp_live_<YOUR_API_KEY>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())