SocialCrawl Tripadvisor API

openapi: 3.2.0
info:
  title: SocialCrawl Tripadvisor API
  version: 1.0.0
  description: 'Unified social media data API - one API key, one consistent response format, 50 platforms, 400 endpoints. Power AI agents with clean social data.


    Slim variant: inline examples removed and the shared error responses hoisted into components. The full annotated spec is at https://www.socialcrawl.dev/openapi.json.'
  contact:
    name: SocialCrawl
    url: https://www.socialcrawl.dev
    email: support@socialcrawl.dev
servers:
- url: https://www.socialcrawl.dev/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: tripadvisor
  description: Tripadvisor endpoints
paths:
  /tripadvisor/search:
    get:
      summary: Search TripAdvisor businesses & places
      description: 'Searches TripAdvisor for businesses and places (restaurants, hotels, attractions) matching a keyword in a location. Returns a unified PlaceList: each result carries the place name, category, star rating, total review count, and the `url_path` (the `id`/`url` are derived from it) that you pass to /v1/tripadvisor/reviews to pull that place''s reviews. Results are location-bound (default: United States). Sourced from DataForSEO''s task-based Business Data API; the async lifecycle is handled server-side, so this is an ordinary synchronous request (first calls take ~15-45s, then serve from cache).'
      tags:
      - tripadvisor
      operationId: get_tripadvisor_search
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      parameters:
      - name: q
        in: query
        required: true
        description: Business category, company name, or prominent place (e.g. 'pizza restaurant').
        schema:
          type: string
      - name: location
        in: query
        required: false
        description: 'Full location name (e.g. ''New York,New York,United States''). Default: United States. Results are location-bound.'
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: Optional language code to narrow results, e.g. 'en'.
        schema:
          type: string
      - name: depth
        in: query
        required: false
        description: Number of results to retrieve (multiples of 30, default 30, max 60 on this synchronous endpoint).
        schema:
          type: integer
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      items:
                        type: array
                        description: Array of canonical place wrappers ({ place })
                        items:
                          type: object
                          description: Canonical place wrapper
                          properties:
                            place:
                              type: object
                              description: Canonical Place object (physical/local business or hotel)
                              properties:
                                id:
                                  type: string
                                  description: Place ID (Google cid for a business, hotel_identifier for a hotel)
                                name:
                                  type:
                                  - string
                                  - 'null'
                                  description: Business / hotel name
                                url:
                                  type:
                                  - string
                                  - 'null'
                                  description: Website or canonical URL
                                category:
                                  type:
                                  - string
                                  - 'null'
                                  description: Primary category (e.g. "Coffee shop", "Hotel")
                                rating:
                                  type: object
                                  description: Aggregate rating (value + max)
                                  properties:
                                    value:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at place.rating.value
                                    max:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at place.rating.max
                                reviews_count:
                                  type:
                                  - integer
                                  - 'null'
                                  description: Number of ratings
                                price_level:
                                  type:
                                  - string
                                  - 'null'
                                  description: Price band ("inexpensive" / "$$" / null)
                                address:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at place.address
                                phone:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at place.phone
                                latitude:
                                  type:
                                  - integer
                                  - 'null'
                                  description: Numeric at place.latitude
                                longitude:
                                  type:
                                  - integer
                                  - 'null'
                                  description: Numeric at place.longitude
                                verified:
                                  type:
                                  - boolean
                                  - 'null'
                                  description: Claimed-business flag (Google is_claimed)
                                description:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at place.description
                                image_urls:
                                  type:
                                  - string
                                  - array
                                  - 'null'
                                  description: 'Union: string | array | null'
                                  items:
                                    type: string
                                    description: String at place.image_urls
                                categories:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at place.categories
                                  items:
                                    type: string
                                    description: String at place.categories
                                hotel:
                                  type:
                                  - object
                                  - 'null'
                                  description: Hotel-only richness (stars, amenities, review topics, prices); null for plain places
                                  properties:
                                    stars:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at place.hotel.stars
                                    stars_description:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at place.hotel.stars_description
                                    check_in_time:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at place.hotel.check_in_time
                                    check_out_time:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at place.hotel.check_out_time
                                    amenities:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at place.hotel.amenities
                                      items:
                                        type: object
                                        description: 'Nested object: place.hotel.amenities'
                                        properties:
                                          category:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.hotel.amenities.category
                                          name:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.hotel.amenities.name
                                          available:
                                            type:
                                            - boolean
                                            - 'null'
                                            description: Boolean at place.hotel.amenities.available
                                          hint:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.hotel.amenities.hint
                                    review_topics:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at place.hotel.review_topics
                                      items:
                                        type: object
                                        description: 'Nested object: place.hotel.review_topics'
                                        properties:
                                          title:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.hotel.review_topics.title
                                          positive_score:
                                            type:
                                            - integer
                                            - 'null'
                                            description: Numeric at place.hotel.review_topics.positive_score
                                          positive_count:
                                            type:
                                            - integer
                                            - 'null'
                                            description: Numeric at place.hotel.review_topics.positive_count
                                          negative_count:
                                            type:
                                            - integer
                                            - 'null'
                                            description: Numeric at place.hotel.review_topics.negative_count
                                          total_count:
                                            type:
                                            - integer
                                            - 'null'
                                            description: Numeric at place.hotel.review_topics.total_count
                                    prices:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at place.hotel.prices
                                      items:
                                        type: object
                                        description: 'Nested object: place.hotel.prices'
                                        properties:
                                          title:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.hotel.prices.title
                                          price:
                                            type:
                                            - integer
                                            - 'null'
                                            description: Numeric at place.hotel.prices.price
                                          currency:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.hotel.prices.currency
                                          url:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.hotel.prices.url
                                          official_site:
                                            type:
                                            - boolean
                                            - 'null'
                                            description: Boolean at place.hotel.prices.official_site
                                ext:
                                  type:
                                  - object
                                  - 'null'
                                  description: 'Nested object: place.ext'
                                  properties:
                                    distance:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at place.ext.distance
                                    status:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at place.ext.status
                                    timezone:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at place.ext.timezone
                                    hours:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at place.ext.hours
                                      items:
                                        type: object
                                        description: 'Nested object: place.ext.hours'
                                        properties:
                                          date:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.ext.hours.date
                                          day_name:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.ext.hours.day_name
                                          is_open:
                                            type:
                                            - boolean
                                            - 'null'
                                            description: Boolean at place.ext.hours.is_open
                                          opens_at:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.ext.hours.opens_at
                                          closes_at:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at place.ext.hours.closes_at
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results.
                      total:
                        type:
                        - integer
                        - 'null'
                        description: Total number of matching results, when the upstream provides a count. Omitted otherwise.
                      dropped:
                        type: integer
                        description: Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                    required:
                    - dropped
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                  pagination:
                    type: object
                    description: Cursor state for this page. Present on every list response.
                    properties:
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.
                      has_more:
                        type: boolean
                        description: Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.
                      page_size:
                        type: integer
                        description: Number of items in THIS page.
                    required:
                    - next_cursor
                    - has_more
                    - page_size
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
                - pagination
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
  /tripadvisor/reviews:
    get:
      summary: Get TripAdvisor reviews for a place
      description: 'Returns a unified ReviewList of traveler reviews for a TripAdvisor place, keyed by its `url_path` (`entity_id` on every review). Each review carries the star rating, full text, title, reviewer profile, attached photos, owner/management `responses[]`, the original + translated language (TripAdvisor auto-translates: a `translated` flag marks it), and publish date. Get the `url_path` from /v1/tripadvisor/search. Filter by traveler rating, traveler type, or a keyword. The synchronous endpoint caps `depth` at 30 (deeper history is a future async surface); a place with no matching reviews returns 404 (auto-refunded). Sourced from DataForSEO''s task-based Business Data API (first calls ~15-45s, then cached).'
      tags:
      - tripadvisor
      operationId: get_tripadvisor_reviews
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      parameters:
      - name: url_path
        in: query
        required: true
        description: The TripAdvisor `url_path` of the place (from a search result), e.g. 'Hotel_Review-g60763-d23462501-Reviews-Margaritaville_Times_Square-New_York_City_New_York.html'.
        schema:
          type: string
      - name: depth
        in: query
        required: false
        description: Number of reviews to retrieve (multiples of 10, default 10, max 30 on this synchronous endpoint).
        schema:
          type: integer
      - name: sort_by
        in: query
        required: false
        description: 'Review ordering: `most_recent` or `detailed_reviews`.'
        schema:
          type: string
          enum:
          - most_recent
          - detailed_reviews
      - name: rating
        in: query
        required: false
        description: 'Filter by traveler rating bucket: excellent | very_good | average | poor | terrible.'
        schema:
          type: string
          enum:
          - excellent
          - very_good
          - average
          - poor
          - terrible
      - name: visit_type
        in: query
        required: false
        description: 'Filter by traveler type: families | couples | solo | business | friends.'
        schema:
          type: string
          enum:
          - families
          - couples
          - solo
          - business
          - friends
      - name: search_reviews_keyword
        in: query
        required: false
        description: Only return reviews containing this keyword.
        schema:
          type: string
      - name: translate
        in: query
        required: false
        description: Translate reviews to the place's domain language (default true). The `translated` flag + `original_language` are always returned.
        schema:
          type: boolean
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      items:
                        type: array
                        description: Array of canonical review wrappers ({ review })
                        items:
                          type: object
                          description: Canonical review wrapper
                          properties:
                            review:
                              type: object
                              description: Canonical Review object (shared across commerce platforms)
                              properties:
                                id:
                                  type: string
                                  description: Review ID (parsed from the review URL when not first-class)
                                entity_id:
                                  type:
                                  - string
                                  - 'null'
                                  description: ID of the reviewed entity (e.g. the Amazon ASIN)
                                url:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at review.url
                                title:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at review.title
                                text:
                                  type:
                                  - string
                                  - 'null'
                                  description: Full review body
                                rating:
                                  type: object
                                  description: Star rating (value + max)
                                  properties:
                                    value:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at review.rating.value
                                    max:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at review.rating.max
                                author:
                                  type: object
                                  description: 'Nested object: review.author'
                                  properties:
                                    name:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at review.author.name
                                    avatar_url:
                                      type:
                        

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-tripadvisor-api-openapi.yml