agentscope.service.web.tripadvisor module
TripAdvisor APIs for searching and retrieving location information.
- agentscope.service.web.tripadvisor.tripadvisor_search_location_photos(api_key: str, location_id: str | None = None, query: str | None = None, language: str = 'en') ServiceResponse[source]
Retrieve photos for a specific location using the TripAdvisor API.
- Parameters:
api_key (str) – Your TripAdvisor API key.
location_id (str, optional) – The unique identifier for a location on Tripadvisor. The location ID can be obtained using the tripadvisor_search function
query (str, optional) – The search query to find a location. Required if location_id is not provided.
language (str, optional) – The language for the response. Defaults to ‘en’.
- Returns:
A dictionary with two variables: status and content. The status variable is from the ServiceExecStatus enum, and content is the JSON response from TripAdvisor API or error information, which depends on the status variable.
If successful, the content will be a dictionary with the following structure:
{ 'photo_data': { 'data': [ { 'id': int, 'is_blessed': bool, 'caption': str, 'published_date': str, 'images': { 'thumbnail': { 'height': int, 'width': int, 'url': str }, 'small': { 'height': int, 'width': int, 'url': str }, 'medium': { 'height': int, 'width': int, 'url': str }, 'large': { 'height': int, 'width': int, 'url': str }, 'original': { 'height': int, 'width': int, 'url': str } }, 'album': str, 'source': {'name': str, 'localized_name': str}, 'user': {'username': str} }, ... ] } }
Each item in the ‘data’ list represents a photo associated with the location.
- Return type:
ServiceResponse
Note
Either location_id or query must be provided. If both are provided, location_id takes precedence.
Example
# Using location_id result = tripadvisor_search_location_photos( "your_api_key", location_id="123456", language="en" ) if result.status == ServiceExecStatus.SUCCESS: print(result.content) # Or using a query result = tripadvisor_search_location_photos( "your_api_key", query="Eiffel Tower", language="en" ) if result.status == ServiceExecStatus.SUCCESS: print(result.content)
- Example of successful content:
- {
- ‘photo_data’: {
- ‘data’: [
- {
‘id’: 215321638, ‘is_blessed’: False, ‘caption’: ‘’, ‘published_date’: ‘2016-09-04T20:40:14.284Z’, ‘images’: {
‘thumbnail’: {‘height’: 50, ‘width’: 50, ‘url’: ‘https://media-cdn…/photo0.jpg’}, ‘small’: {‘height’: 150, ‘width’: 150, ‘url’: ‘https://media-cdn…/photo0.jpg’}, ‘medium’: {‘height’: 188, ‘width’: 250, ‘url’: ‘https://media-cdn…/photo0.jpg’}, ‘large’: {‘height’: 413, ‘width’: 550, ‘url’: ‘https://media-cdn…/photo0.jpg’}, ‘original’: {‘height’: 1920, ‘width’: 2560, ‘url’: ‘https://media-cdn…/photo0.jpg’}
}, ‘album’: ‘Other’, ‘source’: {
‘name’: ‘Traveler’, ‘localized_name’: ‘Traveler’
}, ‘user’: {‘username’: ‘EvaFalleth’}
}, # … more photo entries …
]
}
}
- Raises:
ValueError – If neither location_id nor query is provided.
- agentscope.service.web.tripadvisor.tripadvisor_search(api_key: str, query: str, language: str = 'en') ServiceResponse[source]
Search for locations using the TripAdvisor API.
- Parameters:
api_key (str) – Your TripAdvisor API key.
query (str) – The search query.
language (str, optional) – The language for the response. Defaults to ‘en’.
- Returns:
A dictionary with two variables: status and content. The status variable is from the ServiceExecStatus enum, and content is the JSON response from TripAdvisor API or error information, which depends on the status variable.
If successful, the content will be a dictionary with the following structure: {
- ’data’: [
- {
‘location_id’: str, ‘name’: str, ‘address_obj’: {
’street1’: str, ‘street2’: str, ‘city’: str, ‘state’: str, ‘country’: str, ‘postalcode’: str, ‘address_string’: str
}
]
} Each item in the ‘data’ list represents a location matching the search query.
- Return type:
ServiceResponse
Example
result = search_tripadvisor("your_api_key", "Socotra", "en") if result.status == ServiceExecStatus.SUCCESS: print(result.content)
- Example of successful content:
- {
- ‘data’: [
- {
‘location_id’: ‘574818’, ‘name’: ‘Socotra Island’, ‘address_obj’: {
‘street2’: ‘’, ‘city’: ‘Aden’, ‘country’: ‘Yemen’, ‘postalcode’: ‘’, ‘address_string’: ‘Aden Yemen’
}
}, {
‘location_id’: ‘25395815’, ‘name’: ‘Tour Socotra’, ‘address_obj’: {
‘street1’: ‘20th Street’, ‘city’: ‘Socotra Island’, ‘state’: ‘Socotra Island’, ‘country’: ‘Yemen’, ‘postalcode’: ‘111’, ‘address_string’: ‘20th Street, Socotra Island 111 Yemen’
}
}, # … more results …
]
}
- agentscope.service.web.tripadvisor.tripadvisor_search_location_details(api_key: str, location_id: str | None = None, query: str | None = None, language: str = 'en', currency: str = 'USD') ServiceResponse[source]
Get detailed information about a specific location using the TripAdvisor API.
- Parameters:
api_key (str) – Your TripAdvisor API key.
location_id (str, optional) – The unique identifier for the location. Required if query is not provided.
query (str, optional) – The search query to find a location. Required if location_id is not provided.
language (str, optional) – The language for the response. Defaults to ‘en’, ‘zh’ for Chinese.
currency (str, optional) – The currency code to use for request and response (should follow ISO 4217). Defaults to ‘USD’.
- Returns:
A dictionary with two variables: status and content. The status variable is from the ServiceExecStatus enum, and content is the JSON response from TripAdvisor API or error information, which depends on the status variable.
If successful, the content will be a dictionary with detailed information about the location, including name, address, ratings, reviews, and more.
- Return type:
ServiceResponse
Note
Either location_id or query must be provided. If both are provided, location_id takes precedence.
Example
# Using location_id result = get_tripadvisor_location_details( "your_api_key", location_id="574818", language="en", currency="USD" ) if result.status == ServiceExecStatus.SUCCESS: print(result.content) # Or using a query result = get_tripadvisor_location_details( "your_api_key", query="Socotra Island", language="en", currency="USD" ) if result.status == ServiceExecStatus.SUCCESS: print(result.content)
- Example of successful content:
- {
‘location_id’: ‘574818’, ‘name’: ‘Socotra Island’, ‘web_url’: ‘https://www.tripadvisor.com/Attraction_Review…’, ‘address_obj’: {
‘street2’: ‘’, ‘city’: ‘Aden’, ‘country’: ‘Yemen’, ‘postalcode’: ‘’, ‘address_string’: ‘Aden Yemen’
}, ‘ancestors’: [
{‘level’: ‘City’, ‘name’: ‘Aden’, ‘location_id’: ‘298087’}, {‘level’: ‘Country’, ‘name’: ‘Yemen’, ‘location_id’: ‘294014’}
], ‘latitude’: ‘12.46342’, ‘longitude’: ‘53.82374’, ‘timezone’: ‘Asia/Aden’, ‘write_review’: ‘https://www.tripadvisor.com/UserReview…’, ‘ranking_data’: {
‘geo_location_id’: ‘298087’, ‘ranking_string’: ‘#1 of 7 things to do in Aden’, ‘geo_location_name’: ‘Aden’, ‘ranking_out_of’: ‘7’, ‘ranking’: ‘1’
}, ‘rating’: ‘5.0’, ‘rating_image_url’: ‘https://www.tripadvisor.com/…/5.svg’, ‘num_reviews’: ‘62’, ‘review_rating_count’: {
‘1’: ‘1’, ‘2’: ‘0’, ‘3’: ‘1’, ‘4’: ‘1’, ‘5’: ‘59’,
}, ‘photo_count’: ‘342’, ‘see_all_photos’: ‘https://www.tripadvisor.com/Attraction…’, ‘category’: {‘name’: ‘attraction’, ‘localized_name’: ‘Attraction’}, ‘subcategory’: [
{‘name’: ‘nature_parks’, ‘localized_name’: ‘Nature & Parks’}, {‘name’: ‘attractions’, ‘localized_name’: ‘Attractions’}
], ‘groups’: [
- {
‘name’: ‘Nature & Parks’, ‘localized_name’: ‘Nature & Parks’, ‘categories’: [{‘name’: ‘Islands’, ‘localized_name’: ‘Islands’}]
}
], ‘neighborhood_info’: [], ‘trip_types’: [
{‘name’: ‘business’, ‘localized_name’: ‘Business’, ‘value’: ‘2’}, {‘name’: ‘couples’, ‘localized_name’: ‘Couples’, ‘value’: ‘10’}, {‘name’: ‘solo’, ‘localized_name’: ‘Solo travel’, ‘value’: ‘11’}, {‘name’: ‘family’, ‘localized_name’: ‘Family’, ‘value’: ‘2’}, {‘name’: ‘friends’, ‘localized_name’: ‘Friends getaway’, ‘value’: ‘22’}
], ‘awards’: []
}
- Raises:
ValueError – If neither location_id nor query is provided.
