openapi: 3.1.0
info:
  title: Tripadvisor Content Availability Location Search API
  description: The Tripadvisor Content API provides developers with access to Tripadvisor's extensive dataset of more than 7.5 million locations, 1 billion reviews and opinions, and content in 29 languages. The API includes endpoints for location search, nearby search, location details, location photos, and location reviews, enabling developers to integrate rich travel content into their websites and applications. Locations are defined within this API as hotels, restaurants, or attractions. The first 5,000 API calls per month are free for initial development and testing.
  version: '1.0'
  contact:
    name: Tripadvisor Developer Support
    url: https://developer-tripadvisor.com/content-api/
  termsOfService: https://developer-tripadvisor.com/content-api/terms-of-use/
servers:
- url: https://api.content.tripadvisor.com/api/v1
  description: Production Server
security:
- apiKeyQuery: []
tags:
- name: Location Search
  description: Search for locations by keyword query or geographic proximity. Returns up to 10 matching locations per request.
paths:
  /location/search:
    get:
      operationId: searchForLocations
      summary: Search for Locations
      description: Returns up to 10 locations found by the given search query. You can use category, phone number, address, and latitude/longitude to search with more accuracy. Locations include hotels, restaurants, and attractions.
      tags:
      - Location Search
      parameters:
      - $ref: '#/components/parameters/SearchQuery'
      - $ref: '#/components/parameters/Category'
      - $ref: '#/components/parameters/Phone'
      - $ref: '#/components/parameters/Address'
      - $ref: '#/components/parameters/LatLong'
      - $ref: '#/components/parameters/Radius'
      - $ref: '#/components/parameters/RadiusUnit'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Successful location search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationSearchResponse'
        '400':
          description: Bad request due to invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /location/nearby_search:
    get:
      operationId: searchForNearbyLocations
      summary: Search for Nearby Locations
      description: Returns up to 10 locations found near the given latitude and longitude. You can use category, phone number, and address to search with more accuracy. Useful for finding hotels, restaurants, and attractions in proximity to a specific geographic point.
      tags:
      - Location Search
      parameters:
      - $ref: '#/components/parameters/LatLongRequired'
      - $ref: '#/components/parameters/Category'
      - $ref: '#/components/parameters/Phone'
      - $ref: '#/components/parameters/Address'
      - $ref: '#/components/parameters/Radius'
      - $ref: '#/components/parameters/RadiusUnit'
      - $ref: '#/components/parameters/Language'
      responses:
        '200':
          description: Successful nearby search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationSearchResponse'
        '400':
          description: Bad request due to invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized due to missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    SearchQuery:
      name: searchQuery
      in: query
      required: true
      description: The text query to search for matching locations.
      schema:
        type: string
        example: Eiffel Tower
    Address:
      name: address
      in: query
      required: false
      description: Address string to improve search accuracy.
      schema:
        type: string
    RadiusUnit:
      name: radiusUnit
      in: query
      required: false
      description: The unit of measurement for the radius parameter.
      schema:
        type: string
        enum:
        - km
        - mi
        default: km
    LatLongRequired:
      name: latLong
      in: query
      required: true
      description: Latitude and longitude pair for the center of the nearby search. Format is latitude,longitude.
      schema:
        type: string
        pattern: ^-?\d+\.?\d*,-?\d+\.?\d*$
        example: 48.8584,2.2945
    Language:
      name: language
      in: query
      required: false
      description: The language code for the response content. Tripadvisor supports 29 languages.
      schema:
        type: string
        default: en
        example: en
    Radius:
      name: radius
      in: query
      required: false
      description: The radius distance from the latLong point to filter results.
      schema:
        type: number
        format: float
    Category:
      name: category
      in: query
      required: false
      description: Filter results by location category type.
      schema:
        type: string
        enum:
        - hotels
        - attractions
        - restaurants
        - geos
    Phone:
      name: phone
      in: query
      required: false
      description: Phone number to search for a specific location.
      schema:
        type: string
    LatLong:
      name: latLong
      in: query
      required: false
      description: Latitude and longitude pair to bias search results toward a specific geographic area. Format is latitude,longitude.
      schema:
        type: string
        pattern: ^-?\d+\.?\d*,-?\d+\.?\d*$
        example: 48.8584,2.2945
  schemas:
    Address:
      type: object
      description: The physical address of a location.
      properties:
        street1:
          type: string
          description: The primary street address line.
        street2:
          type: string
          description: The secondary street address line.
        city:
          type: string
          description: The city name.
        state:
          type: string
          description: The state or province name.
        country:
          type: string
          description: The country name.
        postalcode:
          type: string
          description: The postal or ZIP code.
        address_string:
          type: string
          description: The full formatted address as a single string.
    LocationSearchResponse:
      type: object
      description: Response containing a list of locations matching the search criteria.
      properties:
        data:
          type: array
          description: Array of location summary objects matching the search query, up to 10 results.
          items:
            $ref: '#/components/schemas/LocationSummary'
    LocationSummary:
      type: object
      description: A summary representation of a Tripadvisor location returned in search results.
      properties:
        location_id:
          type: string
          description: The unique Tripadvisor identifier for this location.
        name:
          type: string
          description: The display name of the location.
        address_obj:
          $ref: '#/components/schemas/Address'
    Error:
      type: object
      description: Error response returned when a request fails.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: A human-readable error message describing what went wrong.
            type:
              type: string
              description: The error type classification.
            code:
              type: integer
              description: A numeric error code.
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      name: key
      in: query
      description: API key passed as a query parameter. Obtain your key by registering at the Tripadvisor Developer Portal.
externalDocs:
  description: Tripadvisor Content API Documentation
  url: https://tripadvisor-content-api.readme.io/reference/overview