GET
# Agoda Reviews from URL API

Extract hotel reviews directly from any Agoda hotel URL without needing to know the hotel ID.

## Overview

#### Automatic Hotel ID Extraction

Simply provide any Agoda hotel URL and the API will automatically extract the hotel ID and fetch reviews.

This endpoint simplifies the review extraction process by accepting any valid Agoda hotel URL. The API automatically identifies the hotel ID from the URL and retrieves all review data, making it perfect for applications that work with URLs rather than IDs.

### Endpoint URL

GET https://api.stayapi.com/v1/agoda/hotel/reviews-from-url 

## Supported URL Formats

### Valid Agoda URL Patterns

https://www.agoda.com/hotel-name/hotel/city-country.html

Standard hotel page URL

https://www.agoda.com/hotel-name/hotel/all/city-country.html

Hotel page with all locations

https://www.agoda.com/en-us/hotel-name/hotel/city.html

Localized URL with language prefix

agoda.com/hotel-123456.html

Short format with hotel ID in URL

#### URL Parameters

Query parameters like check-in dates, guest counts, etc. are ignored. Only the hotel identifier is extracted.

## Management replies

Returns Agoda's own guest reviews only; reviews Agoda shows from partner sites are not included; pagination (`total_count`, `has_more`) covers Agoda's own reviews only. The requested page size is 20; actual counts can differ. Agoda lists English-language reviews first (newest first with the default sort), then reviews in other languages, so for a complete date range, page until `has_more` is false. Advertised totals do not guarantee every review is accessible. A hotel with no Agoda reviews returns `200` with `reviews: []` and `total_count` 0; a page Agoda keeps blocking returns `502`, so retry it later.

`reviews[].owner_response` is null when no reply is available, or an object with nullable string fields `text`, `published_date`, and `author`. Reply dates preserve source formatting; ISO format and timezone are not guaranteed. Date and author may be null even when text is present.

```
{"text":"Thank you for your feedback.","published_date":null,"author":"Hotel management"}
```

`review_score` is Agoda's own guest score and rating count (not combined with partner sites), never a page average. Its `review_count` can be higher than `pagination.total_count` because it includes ratings without written reviews. Available aggregates contain nullable `overall`, `score_text`, and `review_count`. Missing aggregates can be an empty object or null; the review comments endpoint may return null. Do not infer an aggregate from the reviews on this page.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| url | string | Required | Full Agoda hotel URL (query parameter) |
| page | integer | Optional | Page number for pagination (starts at 1, default: 1) |
| sorting | integer | Optional | Sort order: 7 = most recent, 6 = highest rating, 5 = lowest rating (default: 7) |

## How It Works

1

### URL Validation

The API validates that the provided URL is from agoda.com domain.

2

### Hotel ID Extraction

The system automatically extracts the hotel ID from the URL by analyzing the page content.

3

### Review Fetching

Reviews are retrieved using the extracted hotel ID with your specified parameters.

4

### Response Delivery

Complete review data is returned in the same format as the standard reviews endpoint.

## Usage Examples

### Basic Review Extraction

Extract reviews from any Agoda hotel page:

 GET /v1/agoda/hotel/reviews-from-url?url=https://www.agoda.com/omena-hotel-jyvaskyla/hotel/jyvaskyla-fi.html 

### With Pagination

Get specific page of reviews (20 reviews per page):

 GET /v1/agoda/hotel/reviews-from-url?url=https://www.agoda.com/hotel-name/hotel/city.html&page=2 

### Sorted by Rating

Get highest-rated reviews first:

 GET /v1/agoda/hotel/reviews-from-url?url=https://www.agoda.com/hotel/city.html&sorting=6 

## Error Handling

400
### Invalid URL

The provided URL is not a valid Agoda hotel URL

```
{
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not a valid Agoda hotel URL"
  }
}
```

400
### Hotel ID Not Found

Could not extract hotel ID from the provided URL

```
{
  "error": {
    "code": "HOTEL_ID_NOT_FOUND",
    "message": "Could not extract hotel ID from the provided URL"
  }
}
```

#### URL Requirements

Ensure the URL points to a valid Agoda hotel page, not search results or other pages.

## Best Practices

### Recommendations

- Validate URLs on the client side before making API calls
- Cache the extracted hotel ID for subsequent requests
- Use URL encoding for special characters in the URL parameter
- Consider using the direct hotel ID endpoint if you already have the ID
- Handle pagination based on the total\_pages returned in the response
- Implement retry logic for temporary extraction failures

Request

```curl
curl -X GET "https://api.stayapi.com/v1/agoda/hotel/reviews-from-url?url=https%3A%2F%2Fwww.agoda.com%2Fomena-hotel-jyvaskyla%2Fhotel%2Fjyvaskyla-fi.html&page=1" \
  -H "X-API-Key: YOUR_API_KEY"
```

Response

```json
{
  "success": true,
  "hotel_id": 319457,
  "hotel_name": "Omena Hotel Jyvaskyla",
  "reviews": [
    {
      "review_id": "1013949992",
      "rating": 10.0,
      "title": "Thanks a lot for Omena Call Support",
      "comment": "Omena Call Support helped me to get my check-in link...",
      "pros": "",
      "cons": "",
      "reviewer": {
        "name": "Shintaro",
        "country": "Japan",
        "level": "",
        "group_type": "Group"
      },
      "date": "August 22, 2025",
      "stay_date": "August 2025",
      "room_type": "Double Room",
      "helpful_count": 0,
      "language": "en",
      "translation": null,
      "photos": [],
      "sub_ratings": {
        "cleanliness": 9.0,
        "location": 9.5,
        "service": 8.0
      },
      "owner_response": {
        "text": "Dear guest, thank you for your kind words! We are glad you enjoyed the location and cleanliness, and we hope to welcome you again soon.",
        "published_date": "2025-08-25T10:15:00+07:00",
        "author": "Hotel Management"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "page_size": 20,
    "total_count": 1459,
    "total_pages": 73,
    "has_more": true
  },
  "review_score": {
    "overall": 7.9,
    "score_text": "Very good",
    "review_count": 1612
  },
  "retrieved_at": "2025-09-04T10:30:00Z"
}
```

```json
{
  "error": {
    "code": "HOTEL_ID_NOT_FOUND",
    "message": "Could not extract hotel ID from the provided URL",
    "status": 400
  }
}
```