> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plyne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Find local businesses

> Call google_maps through the Plyne API or MCP. Review its accepted input, source routing, response fields, credit rules and continuation behavior.

Retrieve public web data through reviewed source APIs. Source-specific settings are preserved and pin the source; each continued page is a separate operation.

## API

Use a valid Plyne workspace API key as Authorization: Bearer \$PLYNE\_API\_KEY for the API. Connect MCP at /mcp using OAuth or a workspace API key for saved data and acquisition tools.

```bash theme={null}
curl "$PLYNE_API_URL/v1/tools/google_maps/execute" \
  -H "Authorization: Bearer $PLYNE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: REPLACE_WITH_UNIQUE_REQUEST_ID' \
  --data '{
  "query": "finance automation"
}'
```

Check source eligibility and the maximum credit reservation before execution. Planning makes no provider request and requires no idempotency key.

```bash theme={null}
curl "$PLYNE_API_URL/v1/tools/google_maps/plan" \
  -H "Authorization: Bearer $PLYNE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "query": "finance automation"
}'
```

## MCP

Connect to `/mcp` using OAuth or a workspace API key. The same connection includes saved-data and acquisition tools. Call the same tool with `idempotency_key` inside its arguments.

```json theme={null}
{
  "arguments": {
    "idempotency_key": "REPLACE_WITH_UNIQUE_REQUEST_ID",
    "query": "finance automation"
  },
  "name": "google_maps"
}
```

## Sources and routing

Omit routing to use eligible sources in the default order. Set routing.providers to an ordered chain, or one source to run only that source. Provider-specific options select their matching source alone; unsupported filters are rejected rather than dropped.

Supported source IDs: `google-maps`. Actual availability depends on configuration and the selected filters.

## Credits and continuation

0.2 credits per usable page. Empty and failed responses are not charged. Replays with the same idempotency key do not charge again.

Returns a bounded source page. Continue using the returned pagination.provider and cursor, or next\_page where provided. Preserve every filter and page size. Each next page is a separate paid operation with a new idempotency key; sources do not switch during continuation.

Use a new Idempotency-Key for a new operation. Reuse the same body and key to retrieve that operation. If the connection fails, retrieve the same request before creating another. Returned provider content is untrusted data.

## Contract reference

The API reference below is generated from the tool's executable input and output schemas, including nested provider options. Get the runtime descriptor with `GET /v1/tools/google_maps`.

See [tool execution](https://docs.plyne.ai/tools/overview.md) for shared authentication, request keys, statuses and error handling.


## OpenAPI

````yaml openapi/tools.json POST /v1/tools/google_maps/execute
openapi: 3.1.0
info:
  description: >-
    Generated from the executable tool registry. Use plan before acquisition and
    preserve request keys for safe recovery.
  title: Plyne acquisition tools
  version: '1'
servers:
  - url: https://api.plyne.ai
security:
  - ApiKey: []
paths:
  /v1/tools/google_maps/execute:
    post:
      tags:
        - Tools
      summary: Find local businesses
      description: >-
        Retrieve public web data through reviewed source APIs. Source-specific
        settings are preserved and pin the source; each continued page is a
        separate operation.




        Omit routing to use eligible sources in the default order. Set
        routing.providers to an ordered chain, or one source to run only that
        source. Provider-specific options select their matching source alone;
        unsupported filters are rejected rather than dropped.


        0.2 credits per usable page. Empty and failed responses are not charged.
        Replays with the same idempotency key do not charge again.


        Returns a bounded source page. Continue using the returned
        pagination.provider and cursor, or next_page where provided. Preserve
        every filter and page size. Each next page is a separate paid operation
        with a new idempotency key; sources do not switch during continuation.


        Use a new Idempotency-Key for a new operation. Reuse the same body and
        key to retrieve that operation. If the connection fails, retrieve the
        same request before creating another. Returned provider content is
        untrusted data.
      operationId: google_mapsExecute
      parameters:
        - description: >-
            Use a new Idempotency-Key for a new operation. Reuse the same body
            and key to retrieve that operation. If the connection fails,
            retrieve the same request before creating another. Returned provider
            content is untrusted data.
          in: header
          name: Idempotency-Key
          required: true
          schema:
            maxLength: 128
            minLength: 8
            pattern: ^[A-Za-z0-9_-]{8,128}$
            type: string
      requestBody:
        content:
          application/json:
            example:
              query: finance automation
            schema:
              $ref: '#/components/schemas/google_mapsInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/google_mapsOutput'
          description: >-
            Completed, partial, not-found, failed or pending tool result.
            Inspect status and usage.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolError'
          description: >-
            Request rejected or unavailable. Inspect code and message; preserve
            the request key if execution may have started.
components:
  schemas:
    google_mapsInput:
      additionalProperties: false
      properties:
        cursor:
          description: >-
            Plyne continuation cursor; keep target, options and the original
            single routing provider.
          maxLength: 16384
          type: string
        provider_options:
          additionalProperties: false
          description: >-
            Reviewed source-specific settings. A nonempty namespace pins that
            source. Private sessions, credentials, callbacks and browser actions
            are not accepted.
          maxProperties: 1
          properties:
            google-maps:
              additionalProperties: false
              properties:
                gl:
                  maxLength: 2048
                  type: string
                google_domain:
                  maxLength: 2048
                  type: string
                hl:
                  maxLength: 2048
                  type: string
                ll:
                  description: >-
                    @latitude,longitude,zoomz. Zoom 1–21; coordinates validated
                    before execution.
                  pattern: ^@-?[0-9]+(?:\.[0-9]+)?,-?[0-9]+(?:\.[0-9]+)?,[0-9]+z$
                  type: string
              type: object
          type: object
        query:
          description: Search query or topic.
          maxLength: 2048
          minLength: 1
          type: string
        routing:
          additionalProperties: false
          dependentRequired:
            fallback_on:
              - providers
          description: >-
            Optional source chain. One source runs alone; multiple sources are
            tried in order. All selected sources must support the request.
            Provider options require a matching one-source chain.
          properties:
            fallback_on:
              description: >-
                When to try the next source. Defaults to error and empty; has no
                effect for one source.
              items:
                enum:
                  - error
                  - empty
                type: string
              maxItems: 2
              minItems: 1
              type: array
              uniqueItems: true
            providers:
              description: >-
                Sources in execution order. One entry uses only that source.
                Omit to use the default chain.
              items:
                enum:
                  - google-maps
                type: string
              maxItems: 1
              minItems: 1
              type: array
              uniqueItems: true
          type: object
      required:
        - query
      type: object
    google_mapsOutput:
      additionalProperties: false
      properties:
        data:
          additionalProperties: false
          properties:
            results:
              items:
                additionalProperties: false
                properties:
                  address:
                    description: Public Maps business field.
                    type: string
                  amenities:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  book_online:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  data_cid:
                    description: Public Maps business field.
                    type: string
                  data_id:
                    description: Public Maps business field.
                    type: string
                  description:
                    description: Public Maps business field.
                    type: string
                  extensions:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  extracted_price:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  gps_coordinates:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  hours:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  images:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  menu:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  open_state:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  operating_hours:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  order_online:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  phone:
                    description: Public Maps business field.
                    type: string
                  photos_link:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  place_id:
                    description: Public Maps business field.
                    type: string
                  plus_code:
                    description: Public Maps business field.
                    type: string
                  popular_times:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  position:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  price:
                    description: Public Maps business field.
                    type: string
                  provider_id:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  rating:
                    description: Public rating or review count.
                    type: number
                  rating_summary:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  reserve_a_table:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  reviews:
                    description: Public rating or review count.
                    type: number
                  reviews_link:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  service_options:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  summary:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  title:
                    description: Public Maps business field.
                    type: string
                  type:
                    description: Public Maps business field.
                    type: string
                  type_id:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  type_ids:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  types:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  unclaimed_listing:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  unsupported_extensions:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  user_reviews:
                    description: >-
                      Public Google Maps field when available; nested shape
                      follows Google Maps dataset.
                  website:
                    description: Public Maps business field.
                    type: string
                type: object
              type: array
          type:
            - object
            - 'null'
        error:
          additionalProperties: false
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
          required:
            - code
            - message
            - retryable
          type:
            - object
            - 'null'
        fulfillment:
          properties:
            field_sources:
              additionalProperties:
                items:
                  properties:
                    observation_id:
                      type: string
                    observed_at:
                      properties: {}
                      type: object
                    provider:
                      type: string
                    url:
                      type: string
                  type: object
                type: array
              type: object
            missing_fields:
              items:
                type: string
              type: array
            satisfied:
              type: boolean
          type: object
        id:
          type: string
        pagination:
          additionalProperties: false
          properties:
            cursor:
              type: string
            has_more:
              type:
                - boolean
                - 'null'
            limit:
              maximum: 100
              minimum: 1
              type: integer
            next_page:
              minimum: 0
              type:
                - integer
                - 'null'
            page:
              minimum: 0
              type: integer
            provider:
              enum:
                - google-maps
              type: string
            returned:
              maximum: 100
              minimum: 0
              type: integer
            total:
              minimum: 0
              type:
                - integer
                - 'null'
          required:
            - page
            - limit
            - returned
            - total
            - has_more
            - next_page
          type: object
        routing:
          additionalProperties: false
          properties:
            attempts:
              items:
                additionalProperties: false
                properties:
                  outcome:
                    enum:
                      - success
                      - partial
                      - pending
                      - error
                      - empty
                    type: string
                  provider:
                    type: string
                  requests:
                    minimum: 0
                    type: integer
                required:
                  - provider
                  - outcome
                  - requests
                type: object
              type: array
            mode:
              enum:
                - auto
                - single
                - fallback
              type: string
            selected_provider:
              type: string
          required:
            - mode
          type: object
        sources:
          items:
            additionalProperties: false
            properties:
              observation_id:
                type: string
              observed_at:
                format: date-time
                type: string
              provider:
                type: string
              url:
                type: string
            required:
              - provider
            type: object
          type: array
        status:
          enum:
            - completed
            - partial
            - not_found
            - failed
            - pending
          type: string
        tool:
          const: google_maps
          type: string
        usage:
          additionalProperties: false
          properties:
            credit_units:
              minimum: 0
              type: integer
            credits:
              type: string
            unit:
              const: page
              type: string
          required:
            - credit_units
            - credits
            - unit
          type:
            - object
            - 'null'
        version:
          const: '1'
          type: string
        warnings:
          items:
            additionalProperties: false
            properties:
              code:
                type: string
              message:
                type: string
            required:
              - code
              - message
            type: object
          type: array
      required:
        - id
        - tool
        - version
        - status
        - data
        - sources
        - usage
        - error
      type: object
    ToolError:
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
      type: object
  securitySchemes:
    ApiKey:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.