Vendasta SEO Service API

openapi: 3.2.0
info:
  title: Listing Products SEO Service API
  version: 1.210.0
servers:
- description: Production
  url: https://prod.apigateway.co/grpc
tags:
- name: SEOService
paths:
  /v1/listing-products/get-keyword-data:
    post:
      operationId: SEOService_GetLocalSearchSEOData
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1GetLocalSearchSEODataRequest'
        description: Request to fetch detailed vicinity/local search data for a specific keyword, showing search results from multiple geographic locations around the business.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1GetLocalSearchSEODataResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
          description: An unexpected error response.
      security:
      - OAuth2:
        - business-app
      summary: Get Local Search SEO Data
      tags:
      - SEOService
  /v1/listing-products/keyword/favourite:
    post:
      operationId: SEOService_SaveSEOSettings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1SaveSEOSettingsRequest'
        description: Request to save SEO settings for a business, including local search radius and favorite keywords.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
          description: An unexpected error response.
      security:
      - OAuth2:
        - business-app
      summary: Save SEO Settings
      tags:
      - SEOService
components:
  schemas:
    rpcStatus:
      properties:
        code:
          format: int32
          type: integer
        details:
          items:
            $ref: '#/components/schemas/protobufAny'
          type: array
        message:
          type: string
      type: object
    v1GetLocalSearchSEODataRequest:
      description: Request to fetch detailed vicinity/local search data for a specific keyword, showing search results from multiple geographic locations around the business.
      properties:
        businessId:
          description: Required. The business ID (account group ID) for which to query local search data.
          type: string
        endDate:
          description: Optional. The end date of the date range for which to retrieve local search data.
          format: date-time
          type: string
        keyword:
          description: 'Required. The specific keyword to fetch local search data for. Unlike GetSEODataSummary, this endpoint

            only accepts a single keyword to provide detailed vicinity analysis.'
          type: string
        startDate:
          description: Optional. The start date of the date range for which to retrieve local search data.
          format: date-time
          type: string
      required:
      - businessId
      - keyword
      title: GetLocalSearchSEODataRequest
      type: object
    v1LocalSearchReviews:
      description: LocalSearchReviews contains review information for a business found in local search results.
      properties:
        count:
          description: The total number of reviews for this business, stored as a string to accommodate large numbers.
          type: string
        rating:
          description: The average star rating for this business (typically on a scale of 1.0 to 5.0).
          format: double
          type: number
      type: object
    v1Vicinity:
      default: VICINITY_UNDEFINED
      enum:
      - VICINITY_UNDEFINED
      - VICINITY_CITY
      - VICINITY_A1
      - VICINITY_A2
      - VICINITY_A3
      - VICINITY_A4
      - VICINITY_A5
      - VICINITY_B1
      - VICINITY_B2
      - VICINITY_B3
      - VICINITY_B4
      - VICINITY_B5
      - VICINITY_C1
      - VICINITY_C2
      - VICINITY_C3
      - VICINITY_C4
      - VICINITY_C5
      - VICINITY_D1
      - VICINITY_D2
      - VICINITY_D3
      - VICINITY_D4
      - VICINITY_D5
      - VICINITY_E1
      - VICINITY_E2
      - VICINITY_E3
      - VICINITY_E4
      - VICINITY_E5
      type: string
    v1LocalSearchResult:
      description: 'LocalSearchResult represents a single business that appeared in local search results.

        This message contains details about a business listing found in the search results for a specific keyword and location.'
      properties:
        address:
          description: The street address of the business.
          type: string
        businessName:
          description: The name of the business as it appears in the search results.
          type: string
        claimStatus:
          $ref: '#/components/schemas/v1GBPClaimStatus'
        isMainBusiness:
          description: 'A flag indicating whether this result is the main business being tracked (true) or a competitor (false).

            When true, this represents the business for which SEO data is being collected.'
          type: boolean
        phoneNumber:
          description: The phone number associated with this business listing.
          type: string
        rank:
          description: 'The ranking position of this business in the search results (e.g., "1", "2", "3").

            Lower numbers indicate higher visibility in search results.'
          type: string
        reviews:
          $ref: '#/components/schemas/v1LocalSearchReviews'
        url:
          description: The URL of the business's Google Business Profile or listing page.
          type: string
      type: object
    v1GetLocalSearchSEODataResponse:
      description: Contains detailed vicinity/local search data for a keyword, showing search results from multiple geographic locations around the business.
      properties:
        averageLocalRank:
          description: 'Output only. The average ranking position across all 25 grid points (vicinities) in the Local Search Grid for

            the current/most recent data. This metric represents the business''s average visibility across the

            5x5 grid around the business location. Only grid points with available data are included in the

            calculation. Grid points where the business was not found (rank 0, invalid, or "-") are treated as

            rank 21. Lower values indicate better average positioning across all geographic locations. Compare

            with previous_average_local_rank to analyze visibility trends over time.

            Note: Although this field is a double, the agent response should display only the integer portion.'
          format: double
          readOnly: true
          type: number
        keyword:
          description: Output only. The keyword for which this local search data was collected.
          readOnly: true
          type: string
        localSearchData:
          description: 'Output only. A list of local search data entries, each representing search results from a different geographic

            location (vicinity). Each entry contains results from one of the 25 locations in the 5x5 grid around

            the business, showing which businesses appear in search results at that specific location.'
          items:
            $ref: '#/components/schemas/v1LocalSearchData'
          readOnly: true
          type: array
        previousAverageLocalRank:
          description: 'Output only. The average ranking position across all 25 grid points (vicinities) from the previous/historical

            local search data. This represents the baseline average visibility for comparison with the current

            average_local_rank. Only grid points with available data are included in the calculation. Grid points

            where the business was not found (rank 0, invalid, or "-") are treated as rank 21. Used for trend

            analysis to determine if local search visibility has improved, declined, or remained stable.

            Note: Although this field is a double, the agent response should display only the integer portion.'
          format: double
          readOnly: true
          type: number
        previousLocalSearchData:
          description: 'Output only. Historical local search data entries from the oldest data point within the specified date range.

            This represents baseline data for comparison to show performance changes over time.'
          items:
            $ref: '#/components/schemas/v1LocalSearchData'
          readOnly: true
          type: array
      title: GetLocalSearchSEODataResponse
      type: object
    vendastatypesFieldMask:
      description: "paths: \"f.a\"\n    paths: \"f.b.d\"\n\nHere `f` represents a field in some root message, `a` and `b`\nfields in the message found in `f`, and `d` a field found in the\nmessage in `f.b`.\n\nField masks are used to specify a subset of fields that should be\nreturned by a get operation or modified by an update operation.\nField masks also have a custom JSON encoding (see below).\n\n# Field Masks in Projections\n\nWhen used in the context of a projection, a response message or\nsub-message is filtered by the API to only contain those fields as\nspecified in the mask. For example, if the mask in the previous\nexample is applied to a response message as follows:\n\n    f {\n      a : 22\n      b {\n        d : 1\n        x : 2\n      }\n      y : 13\n    }\n    z: 8\n\nThe result will not contain specific values for fields x,y and z\n(their value will be set to the default, and omitted in proto text\noutput):\n\n\n    f {\n      a : 22\n      b {\n        d : 1\n      }\n    }\n\nA repeated field is not allowed except at the last position of a\npaths string.\n\nIf a FieldMask object is not present in a get operation, the\noperation applies to all fields (as if a FieldMask of all fields\nhad been specified).\n\nNote that a field mask does not necessarily apply to the\ntop-level response message. In case of a REST get operation, the\nfield mask applies directly to the response, but in case of a REST\nlist operation, the mask instead applies to each individual message\nin the returned resource list. In case of a REST custom method,\nother definitions may be used. Where the mask applies will be\nclearly documented together with its declaration in the API.  In\nany case, the effect on the returned resource/resources is required\nbehavior for APIs.\n\n# Field Masks in Update Operations\n\nA field mask in update operations specifies which fields of the\ntargeted resource are going to be updated. The API is required\nto only change the values of the fields as specified in the mask\nand leave the others untouched. If a resource is passed in to\ndescribe the updated values, the API ignores the values of all\nfields not covered by the mask.\n\nIf a repeated field is specified for an update operation, the existing\nrepeated values in the target resource will be overwritten by the new values.\nNote that a repeated field is only allowed in the last position of a `paths`\nstring.\n\nIf a sub-message is specified in the last position of the field mask for an\nupdate operation, then the existing sub-message in the target resource is\noverwritten. Given the target message:\n\n    f {\n      b {\n        d : 1\n        x : 2\n      }\n      c : 1\n    }\n\nAnd an update message:\n\n    f {\n      b {\n        d : 10\n      }\n    }\n\nthen if the field mask is:\n\n paths: \"f.b\"\n\nthen the result will be:\n\n    f {\n      b {\n        d : 10\n      }\n      c : 1\n    }\n\nHowever, if the update mask was:\n\n paths: \"f.b.d\"\n\nthen the result would be:\n\n    f {\n      b {\n        d : 10\n        x : 2\n      }\n      c : 1\n    }\n\nIn order to reset a field's value to the default, the field must\nbe in the mask and set to the default value in the provided resource.\nHence, in order to reset all fields of a resource, provide a default\ninstance of the resource and set all fields in the mask, or do\nnot provide a mask as described below.\n\nIf a field mask is not present on update, the operation applies to\nall fields (as if a field mask of all fields has been specified).\nNote that in the presence of schema evolution, this may mean that\nfields the client does not know and has therefore not filled into\nthe request will be reset to their default. If this is unwanted\nbehavior, a specific service may require a client to always specify\na field mask, producing an error if not.\n\nAs with get operations, the location of the resource which\ndescribes the updated values in the request message depends on the\noperation kind. In any case, the effect of the field mask is\nrequired to be honored by the API.\n\n## Considerations for HTTP REST\n\nThe HTTP kind of an update operation which uses a field mask must\nbe set to PATCH instead of PUT in order to satisfy HTTP semantics\n(PUT must only be used for full updates).\n\n# JSON Encoding of Field Masks\n\nIn JSON, a field mask is encoded as a single string where paths are\nseparated by a comma. Fields name in each path are converted\nto/from lower-camel naming conventions.\n\nAs an example, consider the following message declarations:\n\n    message Profile {\n      User user = 1;\n      Photo photo = 2;\n    }\n    message User {\n      string display_name = 1;\n      string address = 2;\n    }\n\nIn proto a field mask for `Profile` may look as such:\n\n    mask {\n      paths: \"user.display_name\"\n      paths: \"photo\"\n    }\n\nIn JSON, the same mask is represented as below:\n\n    {\n      mask: \"user.displayName,photo\"\n    }\n\n# Field Masks and Oneof Fields\n\nField masks treat fields in oneofs just as regular fields. Consider the\nfollowing message:\n\n    message SampleMessage {\n      oneof test_oneof {\n        string name = 4;\n        SubMessage sub_message = 9;\n      }\n    }\n\nThe field mask can be:\n\n    mask {\n      paths: \"name\"\n    }\n\nOr:\n\n    mask {\n      paths: \"sub_message\"\n    }\n\nNote that oneof type names (\"test_oneof\" in this case) cannot be used in\npaths."
      properties:
        paths:
          description: The set of field mask paths.
          items:
            type: string
          type: array
      title: '`FieldMask` represents a set of symbolic field paths, for example:'
      type: object
    v1GBPClaimStatus:
      default: GBP_CLAIM_STATUS_INVALID
      description: GBPClaimStatus indicates whether a Google Business Profile listing has been claimed by the business owner.
      enum:
      - GBP_CLAIM_STATUS_INVALID
      - GBP_CLAIM_STATUS_UNKNOWN
      - GBP_CLAIM_STATUS_CLAIMED
      - GBP_CLAIM_STATUS_UNCLAIMED
      type: string
    v1LocalSearchData:
      description: 'LocalSearchData represents search results from a specific geographic location (vicinity) for a keyword.

        This message contains all businesses that appeared in local search results when searching from that location.'
      properties:
        keyword:
          description: The keyword phrase that was searched for at this location.
          type: string
        results:
          description: 'A list of businesses that appeared in the local search results at this location, ordered by their

            ranking position. This shows which businesses are visible when searching from this specific geographic point.'
          items:
            $ref: '#/components/schemas/v1LocalSearchResult'
          type: array
        searchLocation:
          $ref: '#/components/schemas/v1Geo'
        vicinity:
          $ref: '#/components/schemas/v1Vicinity'
      type: object
    v1SaveSEOSettingsRequest:
      description: Request to save SEO settings for a business, including local search radius and favorite keywords.
      properties:
        businessId:
          description: Required. The business ID (account group ID) for which to save SEO settings.
          type: string
        favoriteKeywords:
          description: Optional. The list of favorite keywords for this business.
          items:
            type: string
          type: array
        fieldMask:
          $ref: '#/components/schemas/vendastatypesFieldMask'
        isFullSearchEnabled:
          description: Optional. Whether full search is enabled for this business.
          type: boolean
        localSearchRadius:
          description: Optional. The local search radius to use for keyword tracking.
          format: double
          type: number
      required:
      - businessId
      title: SaveSEOSettingsRequest
      type: object
    v1Geo:
      description: Represents a geo point location.
      properties:
        latitude:
          format: double
          type: number
        longitude:
          format: double
          type: number
      type: object
    protobufAny:
      additionalProperties: {}
      properties:
        '@type':
          type: string
      type: object
  securitySchemes:
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-prod.apigateway.co/oauth2/auth
          scopes:
            admin: Allows the application to perform administrative tasks that you have access to across the platform
            business-app: Allows the application to manage all features of Business App
          tokenUrl: https://sso-api-prod.apigateway.co/oauth2/token
      type: oauth2