Search Google Maps Places

POST/v1/google-maps/search

Runs bounded, low-frequency Google Maps place search over the server-owned HTTP protocol over managed dynamic proxy egress. A completed search costs 10 Credits plus 3 Credits per unique returned place; internal pagination is free.

On this page

Request example

Replace placeholders with your values. Use your Team API key for authenticated requests.

API base https://kieapi.com

curl -X POST "https://kieapi.com/v1/google-maps/search" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'Idempotency-Key: docs-example-01' \
  -H "Content-Type: application/json" \
  -d '{
  "keyword": "<value>",
  "latitude": -90,
  "longitude": -180,
  "viewport_span": 1
}'

Authentication

BearerAuth

Parameters

Idempotency-Key header · string: Caller-generated key, up to 128 characters, that identifies one API Market write and its billing event. Reuse the same key only when retrying the same logical request. Replays do not create another reservation or capture.

Request body required

application/json

GoogleMapsSearchRequest

keyword string required
latitude number required
longitude number required
viewport_span number required
page_size integer: Default: 20
max_pages integer: Default: 1

Responses

200 Normalized Google Maps search results and page proof.

application/json

GoogleMapsSearchResponse

query GoogleMapsSearchQuery required
results array of GoogleMapsPlace required
pages array of GoogleMapsPageProof required
termination string required: Allowed: "short_page", "page_budget_exhausted"
page_count integer required
total_unique_results integer required

400 Request validation failed.

application/json

PublicErrorResponse

error PublicError required

401 Missing or invalid API key.

application/json

PublicErrorResponse

error PublicError required

402 The Team does not have enough available Credits for the maximum reservation.

application/json

PublicErrorResponse

error PublicError required

403 Authenticated principal cannot access this resource.

application/json

PublicErrorResponse

error PublicError required

409 Billing settlement requires reconciliation, or the idempotency key was reused for a different logical request.

application/json

PublicErrorResponse

error PublicError required

429 Temporary rate limit.

application/json

PublicErrorResponse

error PublicError required

502 Upstream fetch or network failure.

application/json

PublicErrorResponse

error PublicError required

503 Required runtime service is unavailable.

application/json

PublicErrorResponse

error PublicError required

Schemas

Field definitions and complete validation rules for this API. Follow a type link to its definition.

GoogleMapsSearchRequest

object

keyword string required
latitude number required
longitude number required
viewport_span number required
page_size integer: Default: 20
max_pages integer: Default: 1

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "keyword",
    "latitude",
    "longitude",
    "viewport_span"
  ],
  "properties": {
    "keyword": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "^[^!]+$"
    },
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "viewport_span": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 100000000
    },
    "page_size": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 20
    },
    "max_pages": {
      "type": "integer",
      "minimum": 1,
      "maximum": 5,
      "default": 1
    }
  }
}

GoogleMapsSearchResponse

object

query GoogleMapsSearchQuery required
results array of GoogleMapsPlace required
pages array of GoogleMapsPageProof required
termination string required: Allowed: "short_page", "page_budget_exhausted"
page_count integer required
total_unique_results integer required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "query",
    "results",
    "pages",
    "termination",
    "page_count",
    "total_unique_results"
  ],
  "properties": {
    "query": {
      "$ref": "#/components/schemas/GoogleMapsSearchQuery"
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GoogleMapsPlace"
      }
    },
    "pages": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/GoogleMapsPageProof"
      }
    },
    "termination": {
      "type": "string",
      "enum": [
        "short_page",
        "page_budget_exhausted"
      ]
    },
    "page_count": {
      "type": "integer",
      "minimum": 0
    },
    "total_unique_results": {
      "type": "integer",
      "minimum": 0
    }
  }
}

GoogleMapsSearchQuery

object

keyword string required
center GoogleMapsCoordinates required
viewport_span number required
page_size integer required
max_pages integer required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "keyword",
    "center",
    "viewport_span",
    "page_size",
    "max_pages"
  ],
  "properties": {
    "keyword": {
      "type": "string"
    },
    "center": {
      "$ref": "#/components/schemas/GoogleMapsCoordinates"
    },
    "viewport_span": {
      "type": "number"
    },
    "page_size": {
      "type": "integer"
    },
    "max_pages": {
      "type": "integer"
    }
  }
}

GoogleMapsCoordinates

object

latitude number | null
longitude number | null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "latitude": {
      "type": [
        "number",
        "null"
      ]
    },
    "longitude": {
      "type": [
        "number",
        "null"
      ]
    }
  }
}

GoogleMapsPlace

object

rank integer | null
data_id string required
name string required
category string | null
address string | null
coordinates GoogleMapsCoordinates required
rating number | null
domain string | null
website string | null
phone_display string | null
phone_e164 string | null
telephone_uri string | null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data_id",
    "name",
    "coordinates"
  ],
  "properties": {
    "rank": {
      "type": [
        "integer",
        "null"
      ]
    },
    "data_id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "category": {
      "type": [
        "string",
        "null"
      ]
    },
    "address": {
      "type": [
        "string",
        "null"
      ]
    },
    "coordinates": {
      "$ref": "#/components/schemas/GoogleMapsCoordinates"
    },
    "rating": {
      "type": [
        "number",
        "null"
      ]
    },
    "domain": {
      "type": [
        "string",
        "null"
      ]
    },
    "website": {
      "type": [
        "string",
        "null"
      ]
    },
    "phone_display": {
      "type": [
        "string",
        "null"
      ]
    },
    "phone_e164": {
      "type": [
        "string",
        "null"
      ]
    },
    "telephone_uri": {
      "type": [
        "string",
        "null"
      ]
    }
  }
}

GoogleMapsPageProof

object

offset integer required
status_code integer required
response_bytes integer required
result_count integer required
overlap_with_earlier_pages integer required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "offset",
    "status_code",
    "response_bytes",
    "result_count",
    "overlap_with_earlier_pages"
  ],
  "properties": {
    "offset": {
      "type": "integer",
      "minimum": 0
    },
    "status_code": {
      "type": "integer"
    },
    "response_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "result_count": {
      "type": "integer",
      "minimum": 0
    },
    "overlap_with_earlier_pages": {
      "type": "integer",
      "minimum": 0
    }
  }
}

PublicErrorResponse

object

error PublicError required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "$ref": "#/components/schemas/PublicError"
    }
  }
}

PublicError

object

code string required: Allowed: "seoapi_price_pending", "seoapi_unavailable", "seoapi_busy", "seoapi_not_found", "seoapi_rate_limited", "seoapi_budget_exceeded", "seoapi_idempotency_conflict", "seoapi_insufficient_credits", "seoapi_admission_failed", "seoapi_execution_interrupted", "seoapi_delivery_unknown", "seoapi_response_invalid", "seoapi_model_unsupported", "seoapi_model_options_invalid", "seoapi_provider_rejected", "seo_price_pending", "seo_provider_blocked", "seo_local_rate_limited", "seo_fallback_unavailable", "seo_fallback_budget_exceeded", "seo_pagination_expired", "seo_delivery_uncertain", "seo_auth_required", "seo_initialization_required", "seo_permission_denied", "seo_verification_required", "seo_rate_limited", "seo_upstream_unavailable", "seo_transport_failed", "seo_invalid_response", "seo_rpc_error", "seo_period_unavailable", "seo_account_unavailable", "seo_session_busy", "seo_configuration_required", "validation_error", "invalid_request", "unsupported_feature", "authentication_required", "permission_denied", "not_found", "run_not_found", "crawl_not_found", "artifact_not_found", "session_not_found", "profile_not_found", "profile_in_use", "profile_not_ready", "profile_not_cloneable", "profile_limit_reached", "profile_proxy_conflict", "proxy_not_found", "proxy_unavailable", "invalid_session_options", "invalid_query_options", "invalid_cursor", "idempotency_key_required", "browser_session_limit_reached", "browser_capacity_exhausted", "browser_start_timeout", "browser_runtime_unavailable", "session_not_active", "controller_already_connected", "browser_relay_unavailable", "precondition_required", "precondition_failed", "timeout", "run_not_ready", "artifact_expired", "quota_exceeded", "insufficient_credits", "billing_reconciliation_required", "rate_limited", "fetch_failed", "render_failed", "maps_rate_limited", "maps_challenge", "maps_schema_changed", "maps_invalid_response", "maps_transport_failed", "maps_page_budget_exhausted", "google_trends_rate_limited", "google_trends_challenge", "google_trends_explore_failed", "google_trends_widget_missing", "google_trends_related_failed", "google_trends_invalid_response", "google_trends_transport_failed", "google_trends_collection_failed", "google_ads_account_context_missing", "google_ads_batch_failed", "google_ads_browser_context_missing", "google_ads_browser_unavailable", "google_ads_collection_failed", "google_ads_page_failed", "google_ads_protocol_drift", "google_ads_rate_limited", "google_ads_timeout", "twitter_provider_unavailable", "twitter_provider_rejected", "twitter_submission_unknown", "wechat_transport_failed", "wechat_rate_limited", "wechat_invalid_response", "wechat_redirect_rejected", "wechat_verification_required", "wechat_parse_failed", "blackhatworld_search_failed", "blackhatworld_no_results", "reddit_read_failed", "idempotency_conflict", "idempotency_in_progress", "service_unavailable", "internal_error"
message string required
type string required: Allowed: "auth", "validation", "quota", "rate_limit", "not_found", "execution", "conflict", "internal"
retryable boolean required
request_id string | null
details object

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message",
    "type",
    "retryable"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "seoapi_price_pending",
        "seoapi_unavailable",
        "seoapi_busy",
        "seoapi_not_found",
        "seoapi_rate_limited",
        "seoapi_budget_exceeded",
        "seoapi_idempotency_conflict",
        "seoapi_insufficient_credits",
        "seoapi_admission_failed",
        "seoapi_execution_interrupted",
        "seoapi_delivery_unknown",
        "seoapi_response_invalid",
        "seoapi_model_unsupported",
        "seoapi_model_options_invalid",
        "seoapi_provider_rejected",
        "seo_price_pending",
        "seo_provider_blocked",
        "seo_local_rate_limited",
        "seo_fallback_unavailable",
        "seo_fallback_budget_exceeded",
        "seo_pagination_expired",
        "seo_delivery_uncertain",
        "seo_auth_required",
        "seo_initialization_required",
        "seo_permission_denied",
        "seo_verification_required",
        "seo_rate_limited",
        "seo_upstream_unavailable",
        "seo_transport_failed",
        "seo_invalid_response",
        "seo_rpc_error",
        "seo_period_unavailable",
        "seo_account_unavailable",
        "seo_session_busy",
        "seo_configuration_required",
        "validation_error",
        "invalid_request",
        "unsupported_feature",
        "authentication_required",
        "permission_denied",
        "not_found",
        "run_not_found",
        "crawl_not_found",
        "artifact_not_found",
        "session_not_found",
        "profile_not_found",
        "profile_in_use",
        "profile_not_ready",
        "profile_not_cloneable",
        "profile_limit_reached",
        "profile_proxy_conflict",
        "proxy_not_found",
        "proxy_unavailable",
        "invalid_session_options",
        "invalid_query_options",
        "invalid_cursor",
        "idempotency_key_required",
        "browser_session_limit_reached",
        "browser_capacity_exhausted",
        "browser_start_timeout",
        "browser_runtime_unavailable",
        "session_not_active",
        "controller_already_connected",
        "browser_relay_unavailable",
        "precondition_required",
        "precondition_failed",
        "timeout",
        "run_not_ready",
        "artifact_expired",
        "quota_exceeded",
        "insufficient_credits",
        "billing_reconciliation_required",
        "rate_limited",
        "fetch_failed",
        "render_failed",
        "maps_rate_limited",
        "maps_challenge",
        "maps_schema_changed",
        "maps_invalid_response",
        "maps_transport_failed",
        "maps_page_budget_exhausted",
        "google_trends_rate_limited",
        "google_trends_challenge",
        "google_trends_explore_failed",
        "google_trends_widget_missing",
        "google_trends_related_failed",
        "google_trends_invalid_response",
        "google_trends_transport_failed",
        "google_trends_collection_failed",
        "google_ads_account_context_missing",
        "google_ads_batch_failed",
        "google_ads_browser_context_missing",
        "google_ads_browser_unavailable",
        "google_ads_collection_failed",
        "google_ads_page_failed",
        "google_ads_protocol_drift",
        "google_ads_rate_limited",
        "google_ads_timeout",
        "twitter_provider_unavailable",
        "twitter_provider_rejected",
        "twitter_submission_unknown",
        "wechat_transport_failed",
        "wechat_rate_limited",
        "wechat_invalid_response",
        "wechat_redirect_rejected",
        "wechat_verification_required",
        "wechat_parse_failed",
        "blackhatworld_search_failed",
        "blackhatworld_no_results",
        "reddit_read_failed",
        "idempotency_conflict",
        "idempotency_in_progress",
        "service_unavailable",
        "internal_error"
      ]
    },
    "message": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "auth",
        "validation",
        "quota",
        "rate_limit",
        "not_found",
        "execution",
        "conflict",
        "internal"
      ]
    },
    "retryable": {
      "type": "boolean"
    },
    "request_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "details": {
      "type": "object",
      "additionalProperties": true
    }
  }
}