Listings API Analytics API

openapi: 3.2.0
info:
  title: Listings Analytics API
  version: 2026-09-09
  description: 'REST API for managing business locations: sync listings across Google, Facebook, Bing and other publishers, respond to reviews, publish posts, and pull local search analytics. Authenticate with an API key from the developer dashboard.


    Try the sandbox day pass, no card required, when it is offered: sign up at https://listingsapi.com/signup?plan=day-pass&campaign=daypass. It covers the locations and listings endpoints and syncs only to listingsAPI demo directories. Agents can use the Day pass operations, which need no key; see https://listingsapi.com/docs/day-pass.'
  contact:
    name: Listings API support
    email: support@listingsapi.com
    url: https://www.listingsapi.com/contact
  termsOfService: https://www.listingsapi.com/terms
  license:
    name: Proprietary (Listings API Terms of Service)
    url: https://www.listingsapi.com/terms
  x-logo:
    url: https://www.listingsapi.com/favicon.svg
servers:
- url: https://listingsapi.com
  description: Production
security:
- apiKey: []
- rapidApiKey: []
  rapidApiHost: []
tags:
- name: Analytics
  description: Per-publisher insights (Google / Facebook / Bing) and indexing rate.
paths:
  /api/v4/locations/{locationId}/facebook-analytics:
    get:
      operationId: facebookInsights
      summary: Facebook v4 metrics for a single location over a date range
      tags:
      - Analytics
      parameters:
      - name: locationId
        in: path
        required: true
        schema:
          oneOf:
          - type: integer
            description: Raw numeric ID
          - type: string
            description: Base64-encoded Relay ID
          format: base64-or-int
        description: Location ID, either the Base64 Relay id (e.g. TG9jYXRpb246MTgwMDI4OQ==) or the raw numeric database id (e.g. 1800289). Both forms resolve to the same location.
      - name: fromDate
        in: query
        required: false
        schema:
          type: string
        description: Start of the range (YYYY-MM-DD). Defaults to a recent window when omitted.
      - name: toDate
        in: query
        required: false
        schema:
          type: string
        description: End of the range (YYYY-MM-DD).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    properties:
                      facebookInsights:
                        $ref: '#/components/schemas/FacebookMetricV4'
                  errors:
                    type: array
                    description: Present when the operation reported a request-level failure. Writes can also report validation nested under `data.<field>.errors` on a 200.
                    items:
                      $ref: '#/components/schemas/ApiError'
              example:
                data:
                  facebookInsights:
                    views:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 120
                    ctaAction:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 5
                    directionsAction:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 3
                    phoneAction:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 2
                    websiteAction:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 9
        '400':
          description: 'Bad request: a malformed filter, an invalid enum value, or a malformed ID. The body carries an `errors` array, or a single `error` object when the request was rejected before it ran (e.g. `SY90001` on `reviewDetails` with no `interactionIds`).'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ApiErrorResponse'
                - $ref: '#/components/schemas/ApiErrorObject'
        '401':
          description: Unauthorized — the API key is missing, malformed, or revoked (`SY90005`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden — the key is valid but not permitted for this resource or operation (`SY90003`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '429':
          description: Rate limit exceeded. Wait `retry_after_seconds` (or the `Retry-After` header) and retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Server error. The body carries a single `error` object with code `INTERNAL_SERVER_ERROR`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorObject'
      description: Returns daily Facebook Page interaction metrics for a location over a date range.
  /api/v4/locations/{locationId}/google-analytics:
    get:
      operationId: googleInsights
      summary: Google My Business v4 metrics for a single location over a date range
      tags:
      - Analytics
      parameters:
      - name: locationId
        in: path
        required: true
        schema:
          oneOf:
          - type: integer
            description: Raw numeric ID
          - type: string
            description: Base64-encoded Relay ID
          format: base64-or-int
        description: Location ID, either the Base64 Relay id (e.g. TG9jYXRpb246MTgwMDI4OQ==) or the raw numeric database id (e.g. 1800289). Both forms resolve to the same location.
      - name: fromDate
        in: query
        required: false
        schema:
          type: string
        description: Start of the range (YYYY-MM-DD). Defaults to a recent window when omitted.
      - name: toDate
        in: query
        required: false
        schema:
          type: string
        description: End of the range (YYYY-MM-DD).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    properties:
                      googleInsights:
                        $ref: '#/components/schemas/GoogleMetricV4'
                  errors:
                    type: array
                    description: Present when the operation reported a request-level failure. Writes can also report validation nested under `data.<field>.errors` on a 200.
                    items:
                      $ref: '#/components/schemas/ApiError'
              example:
                data:
                  googleInsights:
                    total:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 412
                    - startTime: 2025-06-02 00:00:00+00:00
                      value: 388
                    search:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 300
                    maps:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 112
                    directionsAction:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 24
                    phoneAction:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 8
                    websiteAction:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 41
                    businessBookings:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 0
                    businessFoodOrders:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 0
                    businessFoodMenuClicks:
                    - startTime: 2025-06-01 00:00:00+00:00
                      value: 0
        '400':
          description: 'Bad request: a malformed filter, an invalid enum value, or a malformed ID. The body carries an `errors` array, or a single `error` object when the request was rejected before it ran (e.g. `SY90001` on `reviewDetails` with no `interactionIds`).'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ApiErrorResponse'
                - $ref: '#/components/schemas/ApiErrorObject'
        '401':
          description: Unauthorized — the API key is missing, malformed, or revoked (`SY90005`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden — the key is valid but not permitted for this resource or operation (`SY90003`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '429':
          description: Rate limit exceeded. Wait `retry_after_seconds` (or the `Retry-After` header) and retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Server error. The body carries a single `error` object with code `INTERNAL_SERVER_ERROR`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorObject'
      description: Returns daily Google Business Profile interaction metrics for a location over a date range.
  /api/v4/locations/{locationId}/bing-analytics:
    get:
      operationId: bingInsights
      summary: Bing Places v4 metrics for a single location over a date range
      tags:
      - Analytics
      parameters:
      - name: locationId
        in: path
        required: true
        schema:
          oneOf:
          - type: integer
            description: Raw numeric ID
          - type: string
            description: Base64-encoded Relay ID
          format: base64-or-int
        description: Location ID, either the Base64 Relay id (e.g. TG9jYXRpb246MTgwMDI4OQ==) or the raw numeric database id (e.g. 1800289). Both forms resolve to the same location.
      - name: fromDate
        in: query
        required: false
        schema:
          type: string
        description: Start of the range (YYYY-MM-DD). Defaults to a recent window when omitted.
      - name: toDate
        in: query
        required: false
        schema:
          type: string
        description: End of the range (YYYY-MM-DD).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    properties:
                      bingInsights:
                        $ref: '#/components/schemas/BingMetricV4'
                  errors:
                    type: array
                    description: Present when the operation reported a request-level failure. Writes can also report validation nested under `data.<field>.errors` on a 200.
                    items:
                      $ref: '#/components/schemas/ApiError'
              example:
                data:
                  bingInsights:
                    views:
                    - startTime: 2025-06-02 00:00:00+00:00
                      value: 73
                    - startTime: 2025-06-09 00:00:00+00:00
                      value: 58
        '400':
          description: 'Bad request: a malformed filter, an invalid enum value, or a malformed ID. The body carries an `errors` array, or a single `error` object when the request was rejected before it ran (e.g. `SY90001` on `reviewDetails` with no `interactionIds`).'
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ApiErrorResponse'
                - $ref: '#/components/schemas/ApiErrorObject'
        '401':
          description: Unauthorized — the API key is missing, malformed, or revoked (`SY90005`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden — the key is valid but not permitted for this resource or operation (`SY90003`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '429':
          description: Rate limit exceeded. Wait `retry_after_seconds` (or the `Retry-After` header) and retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Server error. The body carries a single `error` object with code `INTERNAL_SERVER_ERROR`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorObject'
      description: Returns weekly Bing Places profile view metrics for a location over a date range.
components:
  schemas:
    MetricDelta:
      type: object
      description: Metric value with optional previous-period comparison.
      properties:
        current:
          type: integer
          format: int32
        previous:
          type: integer
          format: int32
        diff:
          type: integer
          format: int32
        diffPercentage:
          type: number
          format: float
        label:
          type: string
    FacebookMetricV4:
      type: object
      description: Facebook metrics with views and action breakdowns.
      properties:
        views:
          $ref: '#/components/schemas/MetricDelta'
        ctaAction:
          $ref: '#/components/schemas/MetricDelta'
        websiteAction:
          $ref: '#/components/schemas/MetricDelta'
        directionsAction:
          $ref: '#/components/schemas/MetricDelta'
        phoneAction:
          $ref: '#/components/schemas/MetricDelta'
    BingMetricV4:
      type: object
      description: Bing Places metrics.
      properties:
        views:
          $ref: '#/components/schemas/MetricDelta'
    ApiErrorObject:
      type: object
      description: Error response with a single `error` object, returned when a request is rejected before it runs.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable code, e.g. `INTERNAL_SERVER_ERROR`, `ambiguous_sub_category`, `unknown_sub_category`, or an `SYxxxxx` code.
            message:
              type: string
            details:
              type: object
              additionalProperties: true
              description: Extra context, e.g. the ambiguous query and its candidate categories.
    ApiErrorResponse:
      type: object
      description: Error response with an `errors` array, returned for most failures. The HTTP status is derived from the error codes, and `data` is present (usually with the operation key set to `null`).
      required:
      - errors
      properties:
        data:
          type:
          - object
          - 'null'
          additionalProperties: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
    GoogleMetricV4:
      type: object
      description: Google My Business metrics including maps, search and actions.
      properties:
        total:
          $ref: '#/components/schemas/MetricDelta'
        maps:
          $ref: '#/components/schemas/MetricDelta'
        search:
          $ref: '#/components/schemas/MetricDelta'
        websiteAction:
          $ref: '#/components/schemas/MetricDelta'
        directionsAction:
          $ref: '#/components/schemas/MetricDelta'
        phoneAction:
          $ref: '#/components/schemas/MetricDelta'
        directSearch:
          $ref: '#/components/schemas/MetricDelta'
        indirectSearch:
          $ref: '#/components/schemas/MetricDelta'
        bookings:
          $ref: '#/components/schemas/MetricDelta'
        foodOrders:
          $ref: '#/components/schemas/MetricDelta'
        foodMenuClicks:
          $ref: '#/components/schemas/MetricDelta'
    RateLimitError:
      type: object
      description: Rate-limit error response. Also carries the `Retry-After` header and the `RateLimit-*` headers.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - RATE_LIMITED
            message:
              type: string
            retry_after_seconds:
              type: integer
              description: Seconds to wait before retrying. Never less than 1.
            limiting_window:
              type: string
              description: Which window was exhausted, e.g. `minute`, `hour`, `day`.
            correlation_id:
              type: string
              description: Request identifier to quote in support requests.
            doc_url:
              type: string
              format: uri
    ApiError:
      type: object
      description: 'One entry of the `errors` array. `message` is always present and starts with the `SYxxxxx: reason` code prefix when the failure has an error code.'
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable reason, prefixed with the `SYxxxxx` code where one applies.
        code:
          type: string
          description: The `SYxxxxx` error code on its own, when one applies.
        contextInfo:
          type: array
          description: Key/value pairs naming the field or value that failed.
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Authenticate with `Authorization: API <your-key>`.'
    rapidApiKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
      description: RapidAPI marketplace key. Sent with `X-RapidAPI-Host` when calling via the RapidAPI proxy.
    rapidApiHost:
      type: apiKey
      in: header
      name: X-RapidAPI-Host
      description: RapidAPI marketplace host header. Sent with `X-RapidAPI-Key` when calling via the RapidAPI proxy.
externalDocs:
  description: Developer documentation
  url: https://listingsapi.com/docs