Endpoint

POST https://data.reviewdata.ai/retrieve-task/

Description

This endpoint allows you to retrieve task data and review content for completed scraping tasks. All four parameters (foreign_key, api_key, publisher_key, and task_id) are required. The publisher_key should match the publisher name from the original request (e.g., 'maps.google.com', 'yelp.com').

For completed tasks: Returns actual review data from S3 files with pagination support, duplicate removal, and standardized formatting. Reviews are automatically sorted by date (newest first) and deduplicated based on review_id.

For incomplete tasks: Returns task status information without review data.

Request Body

Schema

{
  "api_key": "string",
  "foreign_key": "string",
  "publisher_key": "string",
  "page": "integer",
  "page_size": "integer",
  "task_id": "string"
}

Required Fields

Authentication & Task Parameters

Field	Type	Required	Description
`api_key`	string	Yes	Your API key for authentication
`foreign_key`	string	Yes	Foreign key identifier used when creating the original scraping request
`publisher_key`	string	Yes	Publisher name (e.g., `maps.google.com`, `yelp.com`) to identify the specific publisher task
`task_id`	string	Yes	Unique task identifier for the specific scraping task

Optional Fields

Pagination Parameters

Field	Type	Default	Description
`page`	integer	1	Page number for pagination (minimum: 1)
`page_size`	integer	50	Number of reviews per page (minimum: 1, maximum: 1000)

Example Requests

{
  "api_key": "YOUR_API_KEY_HERE",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6"
}

Response

{
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "batch_id": "TEST_1751004113518_i6yxcl",
    "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "related_task_ids": [],
    "task_status": 200,
    "business": {
        "publisher": "maps.google.com",
        "profile_key": "https://www.google.com/maps/place/@40.7094789,-74.0126167,886m/data=!3m2!1e3!5s0x89c2592f4977ef97:0xf78d57398ac93494!4m7!3m6!1s0x89c25a177d4bf5db:0x84e51f23e8c0a75c!8m2!3d40.7094789!4d-74.0100364!10e1!16s%2Fg%2F1thtf190!5m1!1e1?entry=ttu&g_ep=EgoyMDI1MDY",
        "reviews_urls": [
            "https://prod-data-only-client.s3.amazonaws.com/Review_URLs/9f9d2b5a-085c-4df3-bcca-20928f086925/900e2ff4-2d25-4576-ab18-b9b8e73c0bd6_0.jl"
        ],
        "id": "restaurant_001",
        "name": "McDonald's",
        "tags": [
            "restaurant",
            "pizza",
            "italian",
            "casual"
        ],
        "phone": "+12123852066",
        "address": {
            "zip": "10038",
            "city": "New York",
            "state": "NY",
            "street": "160 Broadway",
            "country": "USA"
        },
        "description": "Classic, long-running fast-food chain known for its burgers & fries."
    },
    "reviews": [
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT25wVFEzWkxPR1ZJYkdWS04zWjNlWEo2ZW01UVZGRRAB",
            "author_name": "Regimorais Raab",
            "author_id": null,
            "rating": 5,
            "text": "Rapidez incrível",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT25wVFEzWkxPR1ZJYkdWS04zWjNlWEo2ZW01UVZGRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOnpTQ3ZLOGVIbGVKN3Z3eXJ6em5QVFE%7C0cLUo1-b2qC%7C?hl=en",
            "posted_at": 1750727938010,
            "review_hash": "f2601fda3fb2e249204ff97d9710acd7",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2pFeFEzSXpjVW8zZUdkalFYQkRiR2hSV2xWdVIzYxAB",
            "author_name": "gloria schuweiler",
            "author_id": null,
            "rating": 3,
            "text": "Some  how they  been getting  my order wrong.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2pFeFEzSXpjVW8zZUdkalFYQkRiR2hSV2xWdVIzYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOjExQ3IzcUo3eGdjQXBDbGhRWlVuR3c%7C0cLP3KjBeBa%7C?hl=en",
            "posted_at": 1750704405791,
            "review_hash": "3de49930bb5221fce5bb352146649726",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2t0bVYyODNNRUo2VWxCMVVGcGhRVGxtYzBKNUxXYxAB",
            "author_name": "Zadran Akram khan",
            "author_id": null,
            "rating": 2,
            "text": "Happy Wellcomen New And Last Chef Akram Zadran",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2t0bVYyODNNRUo2VWxCMVVGcGhRVGxtYzBKNUxXYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOktmV283MEJ6UlB1UFphQTlmc0J5LWc%7C0cKzlVRIta5%7C?hl=en",
            "posted_at": 1750596704474,
            "review_hash": "c11d5ca37c28d429beb161013fdd2c3d",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VLUHNodGJuc18ycFR3EAE",
            "author_name": "Ivana Donev",
            "author_id": null,
            "rating": 4,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VLUHNodGJuc18ycFR3EAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEKPshtbns_2pTw%7CCgwI8oq2wgYQsPr9wQE%7C?hl=en",
            "posted_at": 1749910898406,
            "review_hash": "d7f32bfcdd9e46b23f04b2d69e1fe373",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT214TVVHTjNWMkZzVjFSMlQzQmhSMVoyYWtKZmRuYxAB",
            "author_name": "Ludovic Pagès",
            "author_id": null,
            "rating": 2,
            "text": "C'est déjà le bas du panier en France, ben ce n'est pas mieux sur Broadway à Wall Street. Je ne comprends pas pour quoi ça existe encore. Pour le reste ce resto a un service rapide et des toilettes propres.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT214TVVHTjNWMkZzVjFSMlQzQmhSMVoyYWtKZmRuYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOmxMUGN3V2FsV1R2T3BhR1Z2akJfdnc%7C0cI7yCrlChX%7C?hl=en",
            "posted_at": 1749847949935,
            "review_hash": "56848456ebc3393b5aa98a3134242221",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT20xS1UyWjRNR2hLTUdRd2RERmlVVXd4VDFOblgyYxAB",
            "author_name": "Aaron Moore",
            "author_id": null,
            "rating": 5,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT20xS1UyWjRNR2hLTUdRd2RERmlVVXd4VDFOblgyYxAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOm1KU2Z4MGhKMGQwdDFiUUwxT1NnX2c%7C0cI4FOfmJHX%7C?hl=en",
            "posted_at": 1749832729734,
            "review_hash": "ce4e8f08dbe2fda5d996cf906b553450",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VQX3FpdmVkMHBhSlNREAE",
            "author_name": "Cevdet S A",
            "author_id": null,
            "rating": 5,
            "text": "Like it.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VQX3FpdmVkMHBhSlNREAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEP_qived0paJSQ%7CCgsI5p2pwgYQqMTXfA%7C?hl=en",
            "posted_at": 1749700326261,
            "review_hash": "433aa5e69074d92921cdac0b848ec3fd",
            "language": "en"
        },
        {
            "review_id": "Ci9DQUlRQUNvZENodHljRjlvT2pZelVUQTVVRkp3YVhGa1lUTlBVVk42VWxGcE9GRRAB",
            "author_name": "Vinod Sukhadia",
            "author_id": null,
            "rating": 5,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT2pZelVUQTVVRkp3YVhGa1lUTlBVVk42VWxGcE9GRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CAIQACodChtycF9oOjYzUTA5UFJwaXFkYTNPUVN6UlFpOFE%7C0cHNU251Vof%7C?hl=en",
            "posted_at": 1749649347101,
            "review_hash": "aa0b25c137f7b386a6d392f91b54b5e0",
            "language": "en"
        },
        {
            "review_id": "ChZDSUhNMG9nS0VPM0E4N2k4a2V6SEJ3EAE",
            "author_name": "Husnain Ali",
            "author_id": null,
            "rating": 4,
            "text": "",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChZDSUhNMG9nS0VPM0E4N2k4a2V6SEJ3EAE!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEO3A87i8kezHBw%7CCgwI4c2jwgYQ2Mjj1wE%7C?hl=en",
            "posted_at": 1749608161452,
            "review_hash": "b7e33c65de9262919ad22741f0554832",
            "language": "en"
        },
        {
            "review_id": "ChdDSUhNMG9nS0VJQ0FnSURwX3QtdHJBRRAB",
            "author_name": "Fred Alluso",
            "author_id": null,
            "rating": 4,
            "text": "Clean, noisy, crowded. Most importantly they didn't mess up my coffee order.",
            "url": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sChdDSUhNMG9nS0VJQ0FnSURwX3QtdHJBRRAB!2m1!1s0x0:0x84e51f23e8c0a75c!3m1!1s2@1:CIHM0ogKEICAgIDp_t-trAE%7C0cMTWPpdFWz%7C?hl=en",
            "posted_at": 1692756313115,
            "review_hash": "924067883b209b62d4ffd556179d9634",
            "language": "en"
        }
    ],
    "pagination": {
        "total_reviews": 11820,
        "page": 1,
        "page_size": 10,
        "total_pages": 1182,
        "has_next": true,
        "has_previous": false
    }
}

Response Fields

Task Information

Task Response Fields

Field	Type	Description
`foreign_key`	string	Your original foreign key identifier
`batch_id`	string	Batch identifier for grouping related tasks
`task_id`	string	Unique task identifier
`related_task_ids`	array	Array of related task identifiers
`task_status`	integer	HTTP status code indicating task completion status
`business`	object	Business information object (only for completed tasks)
`reviews`	array	Array of review objects (only for completed tasks)
`pagination`	object	Pagination information (only for completed tasks)

Business Object

Business Object Table

Field	Type	Description
`id`	string	Business identifier
`name`	string	Business name
`tags`	array	Array of business category tags
`phone`	string	Business phone number
`address`	object	Business address information
`publisher`	string	Review publisher/platform (e.g., "maps.google.com")
`profile_key`	string	URL to the business profile on the review platform
`reviews_urls`	array	Array of URLs to raw review data files

Review Object

Review Object Table

Field	Type	Description
`review_id`	string	Unique review identifier
`author_name`	string	Name of the reviewer
`author_id`	string	Unique identifier for the reviewer (nullable)
`rating`	integer	Review rating (1–5)
`text`	string	Review text content
`url`	string	URL to the original review
`posted_at`	integer	Unix timestamp when review was posted
`review_hash`	string	Unique hash for deduplication
`language`	string	Language code of the review

Pagination Object

Pagination Object Table

Field	Type	Description
`total_reviews`	integer	Total number of reviews available
`page`	integer	Current page number
`page_size`	integer	Number of reviews per page
`total_pages`	integer	Total number of pages
`has_next`	boolean	Whether there are more pages
`has_previous`	boolean	Whether there are previous pages

Error Responses

{
  "error": "Task not found",
  "details": {
    "foreign_key": "The specified foreign key does not exist",
    "publisher_key": "The specified publisher key does not exist"
  }
}

Pagination

The API supports pagination for large datasets:

Default page size: 50 reviews per page
Maximum page size: 1000 reviews per page
Minimum page size: 1 review per page
Page numbering: Starts from 1

Pagination Example

// Get first page
const response1 = await fetch('/retrieve-task/', {
  method: 'POST',
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY_HERE',
    foreign_key: 'TEST_1751004113518_i6yxcl',
    publisher_key: 'maps.google.com',
    page: 1,
    page_size: 50,
    task_id: '900e2ff4-2d25-4576-ab18-b9b8e73c0bd6'
  })
});

// Get second page
const response2 = await fetch('/retrieve-task/', {
  method: 'POST',
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY_HERE',
    foreign_key: 'TEST_1751004113518_i6yxcl',
    publisher_key: 'maps.google.com',
    page: 2,
    page_size: 50,
    task_id: '900e2ff4-2d25-4576-ab18-b9b8e73c0bd6'
  })
});

Supported Review Sites

This endpoint supports all configured review sites, including:

maps.google.com
yelp.com
tripadvisor.com
facebook.com
trustpilot.com
And 80+ more review sites

Rate Limiting

This endpoint is subject to rate limiting to ensure fair usage and system stability. The default rate limit is 180 requests per 60 seconds.

Rate Limit Details

Limit: 180 requests per 60-second window
Window: Rolling 60-second window
Scope: Per API key

Rate Limit Headers

All successful responses include rate limit information in the headers:

X-RateLimit-Limit: 180
X-RateLimit-Window: 60s
X-RateLimit-Remaining: 179
X-RateLimit-Reset: 1738200123456

Rate Limit Exceeded Response (429)

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

Headers

X-RateLimit-Limit: 180
X-RateLimit-Window: 60s
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1738200123456
Retry-After: 14
Content-Type: application/json

Response Body

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please wait before retrying.",
    "status": 429,
    "details": {
      "limit_per_minute": 180,
      "window_seconds": 60,
      "remaining": 0,
      "reset_at": 1738200123456,
      "endpoint": "/v1/reviews",
      "method": "POST",
      "api_key": "redacted"
    },
    "suggestion": "Reduce request rate or implement exponential backoff with jitter."
  }
}

Best Practices

Monitor Headers: Check X-RateLimit-Remaining to track your usage
Implement Backoff: Use exponential backoff when approaching limits
Respect Retry-After: Wait for the specified time before retrying
Batch Requests: Combine multiple operations when possible