Response Models

The Response Models define the structure of data returned by the ReviewData API endpoints.

Schema

{
    "status": "string",
    "tasks_id": "string",
    "request_id": "string",
    "foreign_key": "string",
    "publisher_key": "string",
}

Fields

Response Object
Field Type Description
status string Status of the request (usually "success")
tasks_id string (UUID) Scraping task's id
request_id string (UUID) Unique identifier for the request
foreign_key string External request identifier
publisher_key string Review publisher/platform (e.g., "maps.google.com")

Example

{
    "status": "success",
    "tasks_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "request_id": "9f9d2b5a-085c-4df3-bcca-20928f086925",
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "publisher_key": "maps.google.com",
}

Response Examples

Completed Task with Reviews
{
    "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!1sChZDSUhNMG9nS0VLUHNodGJuc18ycFR3EAE!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
    }
}
Task In Progress
{
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "response_message": [
    {
      "status": "in_progress",
      "message": "Task is currently being processed",
      "task_status": 101
    }
  ]
}
Task Queued
{
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "response_message": [
    {
      "status": "queued",
      "message": "Task is queued and waiting to be processed",
      "task_status": 100
    }
  ]
}
Task Failed
{
  "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
  "foreign_key": "TEST_1751004113518_i6yxcl",
  "publisher_key": "maps.google.com",
  "response_message": [
    {
      "status": "failed",
      "message": "Task processing failed",
      "task_status": 500
    }
  ]
}
Status Codes

Task Status Codes

HTTP Status Codes
Code Meaning Description
200OKTask completed successfully
400Bad RequestNo business page found
401UnauthorizedAuthentication error
404Not FoundCould not find Business
422Unprocessable EntityInvalid Payload
429Too Many RequestsRate limiting
450Format ChangeChange detected in page format
451Encryption ErrorPublisher encryption failure
452Geoservice ErrorGeoservice failure
460No ReviewsBusiness has no reviews
461No New ReviewsBusiness has no new reviews
472Google Special CaseSpecial case failure for Google
500Internal Server ErrorUnknown error
503Service UnavailableService unavailable
504Gateway TimeoutProcess timed out
505Fatal ErrorFatal unrecoverable error
530Partial SuccessSome reviews present, but error occurred
532Partial SuccessSome reviews present, but hit max attempts

HTTP Status Codes

HTTP Codes
Code Description
200OK - Request successful
201Created - Resource created successfully
400Bad Request - Invalid request
401Unauthorized - Authentication required
404Not Found - Resource not found
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server error
Best Practices
Response and Data Handling

Response Handling

  1. Status Code Checking: Always check both HTTP status codes and task status codes
  2. Error Handling: Implement comprehensive error handling for all response types
  3. Pagination: Handle pagination properly for large datasets
  4. Base64 Decoding: Decode base64 encoded fields when displaying data

Data Processing

  1. Review Deduplication: Use review hashes to prevent duplicates
  2. Data Validation: Validate review data before processing
  3. Language Detection: Use language codes for internationalization
  4. Date Handling: Convert timestamps to appropriate timezone

Performance

  1. Caching: Cache completed task results
  2. Pagination: Use appropriate page sizes
  3. Polling: Implement exponential backoff for incomplete tasks
  4. Monitoring: Monitor response times and error rates

Related Models