POST /v1/brands/{brand_id}/locations/{location_id}/local-scans

Run a local scan on a place

scope write:locations cost 1 RU rate-limit 10/minute · key idempotent required

Scan the place in one run on one grid: where it ranks in Google Maps' local pack for each search in searches (up to 10, one scan each), and whether Gemini, with Google Search and Google Maps grounding at each point, names it for each question in prompts (up to 5). A question must not name the place's city (near me is fine): one that does answers 400 validation_error. grid_size is 3, 5, 7 and spacing_km up to 20 or auto, the default (set off the first search's centre, read first); the grid is centred on the place's pin or on center_lat and center_lng. Costs one credit per 3 AI answers (points times questions), rounded up, the Maps searches included; reserved at the start, the answers that fail are refunded when the AI grid settles. Charged to the brand owner; ?dry_run=true answers the total. Answers the pending Maps scans and AI grid, which share run_id; read them with GET .../geo-scans/{scan_id} and GET .../ai-geo-scans/{scan_id} until status is completed or failed. When the AI grid cannot be queued it is refunded at once, ai_scan.status is failed and no Maps scan starts (data is empty). Requires the brand owner on Starter or with an active API subscription: 403 brand_plan_required otherwise.

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

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

Header parameters

Idempotency-Key string required

Required with an API key, else 400 idempotency_key_required: a new value per operation (a UUID works). A retry with the same key and body within 24 hours replays the first response instead of running again. Ignored with dry_run=true.

Request body

application/json required

Type: LocalScanCreate

prompts array of string required

Questions as a customer asks them, without the city ("near me" is fine): the point is the place.

min items: 1 · max items: 5
searches array of string required

min items: 1 · max items: 10
center_lat number (nullable) nullable

The grid's centre; null uses the place's pin
center_lng number (nullable) nullable
grid_size integer

N in the NxN grid (3, 5 or 7)

default: `3`
spacing_km number | string

Distance between adjacent grid points, km, or "auto": the centre is read first and the spacing set off how far its results lie (0.4 of their median distance, at least 1 km when fewer than 10 come back, rounded to 0.1, 0.2, 0.3, 0.5, 1, 1.5, 2 or 5 km). Left out, it is auto.

default: `auto`

Example payload

{
  "grid_size": 3,
  "prompts": [
    "best dentist near me",
    "best emergency dentist near me"
  ],
  "searches": [
    "dentist",
    "emergency dentist"
  ],
  "spacing_km": 1.5
}

Responses

Run a local scan on a place application/json

Type: LocalScanRun

ai_scan AiGeoScan required

The AI grid of the questions, with its points.
Show fields

Type: AiGeoScan
- cells_answered integer required
- cells_failed integer required
- cells_total integer required
  
  Points times prompts: one Gemini answer each.
- center_lat number required
- center_lng number required
- credits_charged integer required
  
  Reserved at the start; once settled, what was kept.
- grid_size integer required
- id string required
- location_id string required
  
  The place the grid is centred on.
- point_count integer required
- prompts array of string required
- spacing_km number required
- status enum required
  
  pending, running, completed or failed.
- completed_at string (nullable) nullable
- created_at string (nullable) nullable
- last_error string (nullable) nullable
- object string
  
  Always ai_geo_scan.
  
  default: `ai_geo_scan`
- points array of AiGeoScanPoint
- run_id string (nullable) nullable
  
  The local scan it is part of: its Maps scans share it. Null on an AI grid alone.
- schedule_id string (nullable) nullable
  
  The schedule that ran it; null for a scan by hand.
- visibility_pct number (nullable) nullable
  
  Share of the answered cells that name the brand, 0 to 100.
data array of PlaceGeoScanSummary required

One Maps scan per search.
run_id string required
object string

Always local_scan_run.

default: `local_scan_run`

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"
}

Not enough credits to complete this operation 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": "insufficient_credits",
    "message": "Not enough credits to complete this operation"
  },
  "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"
}

Request body did not match the expected schema 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": "body_validation_error",
    "message": "Request body did not match the expected schema"
  },
  "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 POST \
  --url 'https://api.rankprompt.com/v1/brands/your_brand_id_here/locations/your_location_id_here/local-scans?dry_run=false' \
  --header 'Authorization: Bearer rp_live_<YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <UNIQUE_KEY>' \
  --data '{
  "grid_size": 3,
  "prompts": [
    "best dentist near me",
    "best emergency dentist near me"
  ],
  "searches": [
    "dentist",
    "emergency dentist"
  ],
  "spacing_km": 1.5
}'

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

const url = 'https://api.rankprompt.com/v1/brands/your_brand_id_here/locations/your_location_id_here/local-scans?dry_run=false';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer rp_live_<YOUR_API_KEY>',
    'Idempotency-Key': '<UNIQUE_KEY>',
    'Content-Type': 'application/json'
  },
  body: '{"grid_size":3,"prompts":["best dentist near me","best emergency dentist near me"],"searches":["dentist","emergency dentist"],"spacing_km":1.5}'
};

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/local-scans"

querystring = {"dry_run":"false"}

payload = {
    "grid_size": 3,
    "prompts": ["best dentist near me", "best emergency dentist near me"],
    "searches": ["dentist", "emergency dentist"],
    "spacing_km": 1.5
}
headers = {
    "Authorization": "Bearer rp_live_<YOUR_API_KEY>",
    "Idempotency-Key": "<UNIQUE_KEY>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, params=querystring)

print(response.json())