openapi: 3.0.0
info:
  title: Google Maps Posts API
  description: |
    The Google Maps Posts API returns the posts a business publishes on its Google Business Profile, newest first and 10 per page: updates, events, offers and alerts, with their text, photos, playable videos, call to action, offer terms, dates and share link, plus the business they belong to.

    **Cross-linking**: Pass the `data_id` or `place_id` of a place from the Google Maps, Google Maps Autocomplete or Google Maps Place APIs. The `data_id` and `place_id` of `place_result` work with the Google Maps Place, Google Maps Reviews and Google Maps Photos APIs. Pass `pagination.next_page_token` back as `next_page_token` for the next 10 posts.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Google Maps Posts Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Must be set to google_maps_posts
          schema:
            type: string
            enum: ["google_maps_posts"]
        - name: data_id
          in: query
          required: false
          description: Google Maps data_id of the business. Provide either data_id or place_id
          schema:
            type: string
            pattern: "^0x[0-9a-fA-F]{1,16}:0x[0-9a-fA-F]{1,16}$"
        - name: place_id
          in: query
          required: false
          description: Google place_id of the business, starting with ChIJ. Provide either data_id or place_id
          schema:
            type: string
            pattern: "^ChIJ[A-Za-z0-9_-]{23}$"
        - name: hl
          in: query
          required: false
          description: Language of the date and call to action labels
          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 whose date formats the labels use
          schema:
            type: string
            default: "us"
            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", "cx", "cc", "co", "km", "cg", "cd", "ck", "cr", "ci", "hr", "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", "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", "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", "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"]
        - name: next_page_token
          in: query
          required: false
          description: Copy pagination.next_page_token unchanged from a previous response for the same business to get its next 10 posts. Tokens for another business return an error.
          schema:
            type: string
      x-required-one-of:
        - ["data_id", "place_id"]
      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"
        place_result:
          $ref: "#/components/schemas/PlaceResult"
        posts:
          type: array
          description: Posts of the business, newest first
          items:
            $ref: "#/components/schemas/Post"
        pagination:
          $ref: "#/components/schemas/Pagination"
        error:
          type: string
          description: Error message explaining why no posts were 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 URL of the business 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
        data_id:
          type: string
          description: Google Maps data_id of the business
        place_id:
          type: string
          description: Google place_id of the business
        hl:
          type: string
          description: Language of the labels
        gl:
          type: string
          description: Country of the date formats
        next_page_token:
          type: string
          description: Token of the requested page
    PlaceResult:
      type: object
      properties:
        title:
          type: string
          description: Name of the business
        data_id:
          type: string
          description: Google Maps data_id of the business
        place_id:
          type: string
          description: Google place_id of the business
        ludocid:
          type: string
          description: Google customer id of the business
        thumbnail:
          type: string
          description: URL of the business logo
        phone:
          type: string
          description: Phone number of the business
    Post:
      type: object
      required: [position, post_id]
      properties:
        position:
          type: integer
          description: Position of the post in the business's posts, counted across pages
        post_id:
          type: string
          description: ID of the post
        type:
          type: string
          description: Type of the post
          enum: ["update", "event", "offer", "alert"]
        title:
          type: string
          description: Title of the event or offer
        snippet:
          type: string
          description: Full text of the post
        date:
          type: string
          description: Date the post was published, as Google shows it
        iso_date:
          type: string
          format: date-time
          description: Time the post was published, in ISO 8601 UTC
        schedule:
          type: string
          description: Dates and times of the event or offer, as Google shows them
        images:
          type: array
          description: Photos of the post
          items:
            $ref: "#/components/schemas/Image"
        videos:
          type: array
          description: Videos of the post
          items:
            $ref: "#/components/schemas/Video"
        cta:
          type: string
          description: Label of the post's call to action button
        link:
          type: string
          description: URL the call to action button opens
        phone:
          type: string
          description: Phone number the call to action button dials, in E.164 format
        offer:
          $ref: "#/components/schemas/Offer"
        post_link:
          type: string
          description: Google share link of the post
    Image:
      type: object
      properties:
        image:
          type: string
          description: URL of the photo
        thumbnail:
          type: string
          description: URL of a smaller crop of the photo
    Video:
      type: object
      properties:
        video:
          type: string
          description: URL of the video file
        thumbnail:
          type: string
          description: URL of a preview frame of the video
    Offer:
      type: object
      properties:
        redeem_link:
          type: string
          description: URL where the offer can be redeemed
        terms:
          type: string
          description: Terms and conditions of the offer
    Pagination:
      type: object
      required: [next_page_token]
      properties:
        next_page_token:
          type: string
          description: Token to pass as next_page_token for the next 10 posts
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
