openapi: 3.0.0
info:
  title: Google Maps Contributor Reviews API
  description: |
    The Google Maps Contributor Reviews API returns a Google Maps contributor's public profile and their newest reviews: the contributor's name, picture, Local Guide level, points and contribution counts, the review and rating totals their profile lists, and up to 200 of their newest reviews and star-only ratings, newest first. Each entry carries its rating, dates, likes and the reviewed place with its IDs and rating, plus, when available, its text, original language, translation, aspect ratings, photos and videos, owner response, and the place's address, city, category, price range and coordinates.

    Google Maps returns at most a contributor's newest 200 reviews and ratings, and `reviews` holds star-only ratings as well as written reviews, so compare its length with `search_information.total_reviews` plus `total_ratings`. A contributor whose profile shows its counts but no review list comes back with `contributor` and `search_information` and no `reviews`.

    **Cross-linking**: Each review in a Google Maps Reviews API response carries the reviewer's `user.contributor_id`. Pass it as the `contributor_id` parameter to get that reviewer's profile and reviews. The `data_id` and `place_id` of each review's `place` work with the Google Maps Place, Google Maps Reviews and Google Maps Photos APIs.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Google Maps Contributor Reviews Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Must be set to google_maps_contributor_reviews
          schema:
            type: string
            enum: ["google_maps_contributor_reviews"]
        - name: contributor_id
          in: query
          required: true
          description: ID of a Google Maps contributor, from the reviews[].user.contributor_id field of the Google Maps Reviews API or the digits of a profile link (maps/contrib/<contributor_id>)
          schema:
            type: string
            pattern: '^\d{10,25}$'
        - name: hl
          in: query
          required: false
          description: Language for dates, categories, aspect ratings and review translations
          schema:
            type: string
            enum: ["af", "ak", "sq", "am", "ar", "hy", "az", "eu", "be", "bem", "bn", "bh", "xx-bork", "bs", "br", "bg", "km", "ca", "chr", "ny", "zh-cn", "zh-tw", "co", "hr", "cs", "da", "nl", "xx-elmer", "en", "eo", "et", "ee", "fo", "tl", "fi", "fr", "fy", "gaa", "gl", "ka", "de", "el", "kl", "gn", "gu", "xx-hacker", "ht", "ha", "haw", "iw", "hi", "hu", "is", "ig", "id", "ia", "ga", "it", "ja", "jw", "kn", "kk", "rw", "rn", "xx-klingon", "kg", "ko", "kri", "ku", "ckb", "ky", "lo", "la", "lv", "ln", "lt", "loz", "lg", "ach", "mk", "mg", "my", "ms", "ml", "mt", "mv", "mi", "mr", "mfe", "mo", "mn", "sr-me", "ne", "pcm", "nso", "no", "nn", "oc", "or", "om", "ps", "fa", "xx-pirate", "pl", "pt", "pt-br", "pt-pt", "pa", "qu", "ro", "rm", "nyn", "ru", "gd", "sr", "sh", "st", "tn", "crs", "sn", "sd", "si", "sk", "sl", "so", "es", "es-419", "su", "sw", "sv", "tg", "ta", "tt", "te", "th", "ti", "to", "lua", "tum", "tr", "tk", "tw", "ug", "uk", "ur", "uz", "vu", "vi", "cy", "wo", "xh", "yi", "yo", "zu"]
            default: "en"
        - name: gl
          in: query
          required: false
          description: Country for the search, as a two-letter country code
          schema:
            type: string
            enum: ["af", "al", "dz", "as", "ad", "ao", "ai", "aq", "ag", "ar", "am", "aw", "au", "at", "az", "bs", "bh", "bd", "bb", "by", "be", "bz", "bj", "bm", "bt", "bo", "ba", "bw", "bv", "br", "io", "bn", "bg", "bf", "bi", "kh", "cm", "ca", "cv", "ky", "cf", "td", "cl", "cn", "cx", "cc", "co", "km", "cg", "cd", "ck", "cr", "ci", "hr", "cu", "cy", "cz", "dk", "dj", "dm", "do", "ec", "eg", "sv", "gq", "er", "ee", "et", "fk", "fo", "fj", "fi", "fr", "gf", "pf", "tf", "ga", "gm", "ge", "de", "gh", "gi", "gr", "gl", "gd", "gp", "gu", "gt", "gn", "gw", "gy", "ht", "hm", "va", "hn", "hk", "hu", "is", "in", "id", "ir", "iq", "ie", "il", "it", "jm", "jp", "jo", "kz", "ke", "ki", "kp", "kr", "kw", "kg", "la", "lv", "lb", "ls", "lr", "ly", "li", "lt", "lu", "mo", "mk", "mg", "mw", "my", "mv", "ml", "mt", "mh", "mq", "mr", "mu", "yt", "mx", "fm", "md", "mc", "mn", "ms", "ma", "mz", "mm", "na", "nr", "np", "nl", "nc", "nz", "ni", "ne", "ng", "nu", "nf", "mp", "no", "om", "pk", "pw", "ps", "pa", "pg", "py", "pe", "ph", "pn", "pl", "pt", "pr", "qa", "re", "ro", "ru", "rw", "sh", "kn", "lc", "pm", "vc", "ws", "sm", "st", "sa", "sn", "rs", "sc", "sl", "sg", "sk", "si", "sb", "so", "za", "gs", "es", "lk", "sd", "sr", "sj", "sz", "se", "ch", "sy", "tw", "tj", "tz", "th", "tl", "tg", "tk", "to", "tt", "tn", "tr", "tm", "tc", "tv", "ug", "ua", "ae", "uk", "gb", "us", "um", "uy", "uz", "vu", "ve", "vn", "vg", "vi", "wf", "eh", "ye", "zm", "zw", "gg", "je", "im", "me"]
            default: "us"
        - name: num
          in: query
          required: false
          description: Number of the contributor's newest reviews to return
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 10
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "400":
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: "#/components/schemas/SearchMetadata"
        search_parameters:
          $ref: "#/components/schemas/SearchParameters"
        contributor:
          $ref: "#/components/schemas/Contributor"
        search_information:
          $ref: "#/components/schemas/SearchInformation"
        reviews:
          type: array
          items:
            $ref: "#/components/schemas/Review"
        error:
          type: string
          description: Error message explaining why no profile was returned
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: "Unique identifier for the search request"
        status:
          type: string
          description: "Status of the search request"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the search was created"
        request_time_taken:
          type: number
          description: "Time taken to make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "Google Maps contributor profile URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Engine used for the search
        contributor_id:
          type: string
          description: Contributor ID used for the search
        hl:
          type: string
          description: Language used for the search
        gl:
          type: string
          description: Country used for the search
        num:
          type: integer
          description: Number of reviews requested
    Contributor:
      type: object
      required: [name]
      properties:
        contributor_id:
          type: string
          description: Google Maps contributor ID of the profile
        name:
          type: string
          description: Name of the contributor
        link:
          type: string
          description: URL of the contributor's reviews on Google Maps
        thumbnail:
          type: string
          description: URL of the contributor's profile picture
        description:
          type: string
          description: Introduction the contributor wrote on their profile
        is_local_guide:
          type: boolean
          description: Whether the contributor is a Google Maps Local Guide
        local_guide_level:
          type: integer
          description: Local Guide level of the contributor, from 1 to 10
        points:
          type: integer
          description: Local Guide points the contributor has earned
        points_to_next_level:
          type: integer
          description: Points the contributor still needs to reach the next Local Guide level
        contributions:
          $ref: "#/components/schemas/Contributions"
    Contributions:
      type: object
      description: Contribution counts as the contributor's profile shows them
      properties:
        reviews:
          type: integer
          description: Number of reviews the contributor has written
        ratings:
          type: integer
          description: Number of star ratings the contributor has left without a review
        photos:
          type: integer
          description: Number of photos the contributor has posted
        videos:
          type: integer
          description: Number of videos the contributor has posted
        captions:
          type: integer
          description: Number of photo captions the contributor has written
        tips:
          type: integer
          description: Number of tips the contributor has shared
        answers:
          type: integer
          description: Number of questions about places the contributor has answered
        edits:
          type: integer
          description: Number of place edits the contributor has made
        reported_incorrect:
          type: integer
          description: Number of places the contributor has reported as incorrect
        places_added:
          type: integer
          description: Number of places the contributor has added to Google Maps
        roads_added:
          type: integer
          description: Number of roads the contributor has added to Google Maps
        q_and_a:
          type: integer
          description: Number of questions and answers the contributor has posted
        trip_feedback:
          type: integer
          description: Number of trip feedback answers the contributor has given
        incident_reports:
          type: integer
          description: Number of road incidents the contributor has reported
    SearchInformation:
      type: object
      properties:
        total_reviews:
          type: integer
          description: Number of reviews the contributor's profile lists
        total_ratings:
          type: integer
          description: Number of star ratings without a review the contributor's profile lists
    Review:
      type: object
      required: [position]
      properties:
        position:
          type: integer
          description: Position of the review in the contributor's list, newest first
        review_id:
          type: string
          description: Unique identifier for the review
        link:
          type: string
          description: URL of the review on Google Maps
        source:
          type: string
          description: Site the review was posted on
        text:
          type: string
          description: Text of the review in the language it was written in
        translated_text:
          type: string
          description: Text of the review translated into the hl language
        language:
          type: string
          description: Language code of the text the review was written in
        rating:
          type: integer
          description: Star rating the contributor gave, from 1 to 5
        rating_details:
          $ref: "#/components/schemas/RatingDetails"
        date:
          type: string
          description: Relative date of the review's latest update, as Google Maps shows it
        iso_date:
          type: string
          format: date-time
          description: Date and time of the review's latest update, in ISO 8601 format
        images:
          type: array
          items:
            $ref: "#/components/schemas/ReviewImage"
        response:
          $ref: "#/components/schemas/ReviewResponse"
        likes:
          type: integer
          description: Number of likes on the review
        place:
          $ref: "#/components/schemas/Place"
    RatingDetails:
      type: object
      description: Ratings and localized answers keyed by the aspect name in snake_case, with multiple answers returned as an array of strings.
      additionalProperties:
        oneOf:
          - type: integer
          - type: string
          - type: array
            minItems: 1
            items:
              type: string
    ReviewImage:
      type: object
      properties:
        id:
          type: string
          description: ID of the photo, which works as the photo_id parameter of the Google Maps Photo Meta API
        image:
          type: string
          description: URL of the photo, or of a video's still frame
        video:
          type: string
          description: URL of the highest-resolution playable video file
    ReviewResponse:
      type: object
      properties:
        date:
          type: string
          description: Relative date of the owner's response, as Google Maps shows it
        iso_date:
          type: string
          format: date-time
          description: Date and time of the owner's response, in ISO 8601 format
        text:
          type: string
          description: Text of the owner's response
        translated_text:
          type: string
          description: Text of the owner's response translated into the hl language
    Place:
      type: object
      properties:
        title:
          type: string
          description: Name of the reviewed place
        address:
          type: string
          description: Address of the place
        city:
          type: string
          description: City or locality of the place
        data_id:
          type: string
          description: Google Maps data ID of the place
        place_id:
          type: string
          description: Google place ID of the place
        kgmid:
          type: string
          description: Google Knowledge Graph ID of the place
        type:
          type: string
          description: Main category of the place
        price:
          type: string
          description: Price range of the place
        rating:
          type: number
          description: Average star rating of the place
        reviews:
          type: integer
          description: Total number of reviews of the place
        gps_coordinates:
          $ref: "#/components/schemas/GPSCoordinates"
        thumbnail:
          type: string
          description: URL of the place's photo
    GPSCoordinates:
      type: object
      required: [latitude, longitude]
      properties:
        latitude:
          type: number
          description: Latitude of the place
        longitude:
          type: number
          description: Longitude of the place
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
