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

# Get Google Reviews

> Retrieve recent Google reviews, ratings, and review metadata for a business.

## Description

This endpoint retrieves Google reviews for a business using either a keyword search, Google CID, or Place ID. It returns detailed review information including ratings, review text, reviewer profiles, and more.

## Endpoint

```
POST https://app.dumplingai.com/api/v1/get-google-reviews
```

## Headers

* **Content-Type:** `application/json`
* **Authorization:** Bearer `<API_KEY>` (required)

## Request Body

```json theme={null}
{
  "keyword": "string", // Optional. Business name or search term to find reviews for.
  "cid": "string", // Optional. Google Maps CID (Client ID) for a specific business.
  "placeId": "string", // Optional. Google Maps Place ID for a specific business.
  "reviews": "number", // Optional. Number of reviews to fetch. Default: 10.
  "sortBy": "string" // Optional. Sort order for reviews. Can be "relevant", "newest", "highest_rating", or "lowest_rating". Default: "relevant".
  "language": "string", // Optional. Language code for the reviews (e.g., "en" for English). Default: "en". This is an advanced setting, do not use unless you know what you are doing.
  "location": "string", // Optional. Location context for the search. Default: "London,England,United Kingdom". This is an advanced setting, do not use unless you know what you are doing.
}
```

Note: At least one of `keyword`, `cid`, or `placeId` must be provided.

## Responses

### Success (200)

Returns the reviews and business information.

```json theme={null}
{
  "keyword": "string", // If keyword search was used
  "type": "string",
  "se_domain": "string",
  "location_code": "number",
  "language_code": "string",
  "check_url": "string",
  "datetime": "string",
  "title": "string",
  "sub_title": "string",
  "rating": {
    "rating_type": "string",
    "value": "number",
    "votes_count": "number",
    "rating_max": "number"
  },
  "feature_id": "string",
  "place_id": "string",
  "cid": "string",
  "reviews_count": "number",
  "items_count": "number",
  "items": [
    {
      "type": "string",
      "rank_group": "number",
      "rank_absolute": "number",
      "position": "string",
      "review_text": "string",
      "original_review_text": "string",
      "time_ago": "string",
      "timestamp": "string",
      "rating": {
        "rating_type": "string",
        "value": "number",
        "votes_count": "number",
        "rating_max": "number"
      },
      "reviews_count": "number",
      "photos_count": "number",
      "local_guide": "boolean",
      "profile_name": "string",
      "profile_url": "string",
      "review_url": "string",
      "profile_image_url": "string",
      "owner_answer": "string",
      "original_owner_answer": "string",
      "owner_time_ago": "string",
      "owner_timestamp": "string",
      "review_id": "string",
      "images": [
        {
          "type": "string",
          "alt": "string",
          "url": "string",
          "image_url": "string"
        }
      ]
    }
  ]
}
```

* **Content-Type:** application/json
* **X-RateLimit-Limit:** The rate limit for the user.
* **X-RateLimit-Remaining:** The remaining number of requests for the user.

### Bad Request (400)

Returned if the request is invalid.

```json theme={null}
{
  "error": "Either keyword, cid, or placeId must be provided"
}
```

### Unauthorized (401)

Returned if the API key is invalid or missing.

```json theme={null}
{
  "error": "Invalid or missing Authorization header"
}
```

### Internal Server Error (500)

Returned if there's an error during the review fetching process.

```json theme={null}
{
  "error": "Failed to fetch Google reviews: [error message]"
}
```

## Example Request

```bash theme={null}
curl -X POST https://app.dumplingai.com/api/v1/get-google-reviews \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "keyword": "London Wines",
  "reviews": 20,
  "language": "en",
  "sortBy": "highest_rating"
}'
```

## Notes

* Credit usage is calculated based on the number of reviews:
  * 50 credits per 10 reviews (rounded up)
  * e.g., 11 reviews would cost 100 credits
* The maximum number of reviews that can be fetched in a single request is 4490
* If using a Place ID, it should be in the format returned by Google Maps (e.g., "ChIJrTLr-GyuEmsRBfy61i59si0")
* The CID is Google's unique identifier for a business location. It can be found in the URL when viewing a business on Google Maps

## Rate Limiting

Rate limit headers (`X-RateLimit-Limit` and `X-RateLimit-Remaining`) are included in the response to indicate the user's current rate limit status.


## OpenAPI

````yaml POST /api/v1/get-google-reviews
openapi: 3.0.3
info:
  title: DumplingAI API
  version: 1.0.0
  description: >
    REST API for DumplingAI's content intelligence and automation platform.

    All endpoints are grouped under `/api/v1`; most are secured via Bearer API
    keys unless an operation explicitly sets `security: []`.
servers:
  - url: https://app.dumplingai.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: YouTube
    description: Access metadata, search results, and transcripts from YouTube.
  - name: TikTok
    description: Retrieve TikTok profile, video, follower, and transcript data.
  - name: LinkedIn
    description: Programmatically fetch LinkedIn company and profile data.
  - name: Search
    description: Search-orientated endpoints spanning web, news, maps, and autocomplete.
  - name: Google
    description: Integrations with Google business listings and location data.
  - name: Scraping
    description: Webpage capture, crawling, and structured content extraction utilities.
  - name: Documents
    description: Document processing, conversion, and metadata utilities.
  - name: AI
    description: DumplingAI agent and knowledge base endpoints.
  - name: Developer Tools
    description: Utilities for executing sandboxed code via API.
paths:
  /api/v1/get-google-reviews:
    post:
      tags:
        - Google
      summary: Get Google reviews
      description: >-
        Retrieve recent Google reviews, ratings, and review metadata for a
        business.
      operationId: getGoogleReviews
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleReviewsRequest'
            examples:
              default:
                value:
                  placeId: ChIJN1t_tDeuEmsRUsoyG83frY4
      responses:
        '200':
          description: Google reviews returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleReviewsResponse'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key.
        '500':
          description: Unexpected server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GoogleReviewsRequest:
      type: object
      description: >
        Parameters for fetching Google Business reviews. Provide at least one
        identifier (keyword, cid, or placeId).
      properties:
        keyword:
          type: string
          description: Business name or query string.
        cid:
          type: string
          description: Google CID identifier for the business.
        placeId:
          type: string
          description: Google Place ID for the business.
        reviews:
          type: integer
          minimum: 1
          default: 10
          description: Maximum number of reviews to return.
        language:
          type: string
          default: en
          description: ISO language code for the review content.
        location:
          type: string
          default: London,England,United Kingdom
          description: Location bias used when searching by keyword.
        sortBy:
          type: string
          enum:
            - relevant
            - newest
            - highest_rating
            - lowest_rating
          default: relevant
          description: Sorting strategy for returned reviews.
        requestSource:
          $ref: '#/components/schemas/RequestSource'
      additionalProperties: false
    GoogleReviewsResponse:
      type: object
      properties:
        keyword:
          type: string
          nullable: true
        type:
          type: string
        se_domain:
          type: string
        location_code:
          type: integer
        language_code:
          type: string
        check_url:
          type: string
          format: uri
        datetime:
          type: string
        title:
          type: string
        sub_title:
          type: string
        rating:
          $ref: '#/components/schemas/GoogleReviewRating'
        feature_id:
          type: string
        place_id:
          type: string
        cid:
          type: string
        reviews_count:
          type: integer
        items_count:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/GoogleReview'
      required:
        - type
        - se_domain
        - location_code
        - language_code
        - check_url
        - datetime
        - title
        - rating
        - feature_id
        - place_id
        - cid
        - reviews_count
        - items_count
        - items
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable description of what went wrong.
      required:
        - error
    RequestSource:
      type: string
      description: Optional identifier describing where the API request originated.
      enum:
        - API
        - WEB
        - MAKE_DOT_COM
        - ZAPIER
        - N8N
        - PLAYGROUND
        - DEFAULT_AUTOMATION
        - AGENT_PREVIEW
        - AGENT_LIVE
        - AUTOPILOT
        - STUDIO
    GoogleReviewRating:
      type: object
      properties:
        rating_type:
          type: string
        value:
          type: number
        votes_count:
          type: integer
          nullable: true
        rating_max:
          type: number
      required:
        - rating_type
        - value
        - rating_max
      additionalProperties: false
    GoogleReview:
      type: object
      properties:
        type:
          type: string
        rank_group:
          type: integer
        rank_absolute:
          type: integer
        position:
          type: string
        review_text:
          type: string
        original_review_text:
          type: string
          nullable: true
        time_ago:
          type: string
        timestamp:
          type: string
        rating:
          $ref: '#/components/schemas/GoogleReviewRating'
        reviews_count:
          type: integer
        photos_count:
          type: integer
        local_guide:
          type: boolean
        profile_name:
          type: string
        profile_url:
          type: string
          format: uri
        review_url:
          type: string
          format: uri
        profile_image_url:
          type: string
          format: uri
        owner_answer:
          type: string
          nullable: true
        original_owner_answer:
          type: string
          nullable: true
        owner_time_ago:
          type: string
          nullable: true
        owner_timestamp:
          type: string
          nullable: true
        review_id:
          type: string
        images:
          type: array
          items:
            $ref: '#/components/schemas/GoogleReviewImage'
          nullable: true
      required:
        - type
        - rank_group
        - rank_absolute
        - position
        - review_text
        - time_ago
        - timestamp
        - rating
        - reviews_count
        - photos_count
        - local_guide
        - profile_name
        - profile_url
        - review_url
        - profile_image_url
        - review_id
      additionalProperties: false
    GoogleReviewImage:
      type: object
      properties:
        type:
          type: string
        alt:
          type: string
          nullable: true
        url:
          type: string
          format: uri
        image_url:
          type: string
          format: uri
      required:
        - type
        - url
        - image_url
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````