Skip to main content

Response Examples

This page provides comprehensive examples of API responses for different scenarios and endpoints. These examples match the responses you'll see in the interactive playground.

Request Reviews Response​

Success Response​

When you successfully submit a request for review collection, you'll receive a response like this:

{
    "status": "success",
    "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "request_id": "9f9d2b5a-085c-4df3-bcca-20928f086925",
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "publisher_key": "maps.google.com"
}
Response ID Fields
  • task_id: Use this to check task status and retrieve results
  • request_id: Unique identifier for the submission request
  • foreign_key: Your unique identifier for this request
  • publisher_key: The review platform being processed

Error Response - Invalid API Key​

{
    "error": "Invalid API key",
    "details": {
        "api_key": ["The provided API key is invalid or expired"]
    }
}

Error Response - Missing Required Fields​

{
    "error": "Invalid payload",
    "details": {
        "data": {
            "business": {
                "address": {
                    "street": ["This field is required."]
                }
            }
        }
    }
}

Error Response - Invalid Profile Key​

{
    "error": "Invalid profile key",
    "details": {
        "publishers": {
            "maps.google.com": {
                "profile_key": ["The provided profile key is invalid or inaccessible"]
            }
        }
    }
}

Retrieve Task Responses​

Task In Progress​

When a task is still being processed, you'll receive a response indicating the current status:

{
    "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​

When a task is queued and waiting to be processed:

{
    "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 Completed - Google Maps​

When a task is successfully completed, you'll receive the full review data:

{
    "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
    }
}

Task Completed - TripAdvisor Example​

{
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "batch_id": "TEST_1751004113518_i6yxcl",
    "task_id": "67b75d9d-6139-42b7-8ef3-f8d3c8d18ccb",
    "related_task_ids": [],
    "task_status": 200,
    "business": {
        "publisher": "tripadvisor.com",
        "profile_key": "https://www.tripadvisor.com/Restaurant_Review-g60763-d123456-Reviews-McDonalds-New_York_City_New_York.html",
        "reviews_urls": [
            "https://prod-data-only-client.s3.amazonaws.com/Review_URLs/9f9d2b5a-085c-4df3-bcca-20928f086925/67b75d9d-6139-42b7-8ef3-f8d3c8d18ccb_0.jl"
        ],
        "id": "restaurant_001",
        "name": "McDonald's",
        "tags": [
            "restaurant",
            "fast-food"
        ],
        "phone": "+12123852066",
        "address": {
            "zip": "10038",
            "city": "New York",
            "state": "NY",
            "street": "160 Broadway",
            "country": "USA"
        },
        "description": "Fast food restaurant"
    },
    "reviews": [
        {
            "review_id": "trip_12345678",
            "author_name": "John D",
            "author_id": "user_123",
            "rating": 3,
            "text": "Average fast food experience. Food was as expected, service was quick.",
            "url": "https://www.tripadvisor.com/ShowUserReviews-g60763-d123456-r12345678-McDonalds-New_York_City_New_York.html",
            "posted_at": 1750000000000,
            "review_hash": "abc123def456",
            "language": "en"
        }
    ],
    "pagination": {
        "total_reviews": 156,
        "page": 1,
        "page_size": 10,
        "total_pages": 16,
        "has_next": true,
        "has_previous": false
    }
}

Task Completed - Yelp Example​

{
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "batch_id": "TEST_1751004113518_i6yxcl",
    "task_id": "5950304f-ca5b-4274-a9e5-53c6494e85eb",
    "related_task_ids": [],
    "task_status": 200,
    "business": {
        "publisher": "yelp.com",
        "profile_key": "https://www.yelp.com/biz/mcdonalds-new-york-123",
        "reviews_urls": [
            "https://prod-data-only-client.s3.amazonaws.com/Review_URLs/9f9d2b5a-085c-4df3-bcca-20928f086925/5950304f-ca5b-4274-a9e5-53c6494e85eb_0.jl"
        ],
        "id": "restaurant_001",
        "name": "McDonald's",
        "tags": [
            "restaurant",
            "fast-food"
        ],
        "phone": "+12123852066",
        "address": {
            "zip": "10038",
            "city": "New York",
            "state": "NY",
            "street": "160 Broadway",
            "country": "USA"
        },
        "description": "Fast food restaurant"
    },
    "reviews": [
        {
            "review_id": "yelp_abcd1234",
            "author_name": "Sarah M.",
            "author_id": "yelp_user_456",
            "rating": 4,
            "text": "Quick service and the food was hot. Good location near the subway.",
            "url": "https://www.yelp.com/biz/mcdonalds-new-york-123?hrid=abcd1234",
            "posted_at": 1750100000000,
            "review_hash": "def789ghi012",
            "language": "en"
        }
    ],
    "pagination": {
        "total_reviews": 834,
        "page": 1,
        "page_size": 10,
        "total_pages": 84,
        "has_next": true,
        "has_previous": false
    }
}

Task Failed​

When a task fails, you'll receive an error response with details:

{
    "task_id": "900e2ff4-2d25-4576-ab18-b9b8e73c0bd6",
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "publisher_key": "maps.google.com",
    "task_status": 400,
    "response_message": [
        {
            "status": "failed",
            "message": "Profile key is invalid or inaccessible",
            "error_code": "INVALID_PROFILE_KEY",
            "task_status": 400
        }
    ]
}

Task Not Found​

When trying to retrieve a task that doesn't exist:

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

Webhook Configuration Response​

Successful Webhook Configuration​

{
    "webhook": "https://example.com/webhook",
    "status": "success",
    "message": "Webhook endpoint configured successfully"
}

Webhook Configuration Error​

{
    "error": "Invalid webhook URL",
    "details": {
        "webhook": ["The webhook URL must be a valid HTTPS URL"]
    }
}

Common HTTP Status Codes​

Success Responses (2xx)​

  • 200 OK: Request successful, data returned
  • 201 Created: Resource created successfully (webhooks)

Client Error Responses (4xx)​

  • 400 Bad Request: Invalid request format or missing required fields
  • 401 Unauthorized: Invalid or missing API key
  • 404 Not Found: Task or resource not found
  • 422 Unprocessable Entity: Request format is correct but contains invalid data
  • 429 Too Many Requests: Rate limit exceeded

Server Error Responses (5xx)​

  • 500 Internal Server Error: Server-side error occurred
  • 503 Service Unavailable: Service temporarily unavailable

Response Field Descriptions​

Review Object Fields​

FieldTypeDescription
review_idstringUnique identifier for the review
author_namestringName of the review author
author_idstring/nullPlatform-specific author ID (may be null)
ratingintegerReview rating (1-5)
textstringReview text content
urlstringDirect URL to the review
posted_atintegerUnix timestamp of when review was posted
review_hashstringUnique hash of the review content
languagestringLanguage code of the review

Pagination Object Fields​

FieldTypeDescription
total_reviewsintegerTotal number of reviews available
pageintegerCurrent page number
page_sizeintegerNumber of reviews per page
total_pagesintegerTotal number of pages
has_nextbooleanWhether there are more pages
has_previousbooleanWhether there are previous pages

Business Object Fields​

FieldTypeDescription
publisherstringReview platform (e.g., "maps.google.com")
profile_keystringURL to the business profile
reviews_urlsarrayS3 URLs containing full review data
idstringYour business identifier
namestringBusiness name
tagsarrayBusiness category tags
phonestringBusiness phone number
addressobjectBusiness address details
descriptionstringBusiness description

Task Status Codes​

StatusDescription
100Task queued
101Task in progress
200Task completed successfully
400Task failed (client error)
404Task not found
500Task failed (server error)

Sample Data for Testing​

The playground provides these sample configurations that you can use for testing:

Google Maps Sample Data​

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

TripAdvisor Sample Data​

{
    "task_id": "67b75d9d-6139-42b7-8ef3-f8d3c8d18ccb",
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "publisher_key": "tripadvisor.com"
}

Yelp Sample Data​

{
    "task_id": "5950304f-ca5b-4274-a9e5-53c6494e85eb",
    "foreign_key": "TEST_1751004113518_i6yxcl",
    "publisher_key": "yelp.com"
}

Using Response Data​

Extracting Review Data​

// Example: Process completed task response
const processTaskResponse = (response) => {
    if (response.task_status === 200) {
        console.log(`Task completed successfully!`);
        console.log(`Business: ${response.business.name}`);
        console.log(`Publisher: ${response.business.publisher}`);
        console.log(`Total reviews: ${response.pagination.total_reviews}`);
        
        // Process individual reviews
        response.reviews.forEach((review, index) => {
            console.log(`Review ${index + 1}:`);
            console.log(`  Author: ${review.author_name}`);
            console.log(`  Rating: ${review.rating}/5`);
            console.log(`  Text: ${review.text}`);
            console.log(`  Date: ${new Date(review.posted_at).toLocaleDateString()}`);
        });
        
        // Handle pagination
        if (response.pagination.has_next) {
            console.log(`More pages available: ${response.pagination.total_pages} total`);
        }
    } else {
        console.log(`Task status: ${response.task_status}`);
        if (response.response_message) {
            console.log(`Message: ${response.response_message[0].message}`);
        }
    }
};

Handling Errors​

// Example: Error handling
const handleApiResponse = (response, status) => {
    if (status >= 200 && status < 300) {
        // Success
        return response;
    } else if (status === 401) {
        throw new Error('Invalid API key');
    } else if (status === 404) {
        throw new Error('Task not found');
    } else if (status === 422) {
        // Validation error
        const errors = Object.values(response.details).flat();
        throw new Error(`Validation error: ${errors.join(', ')}`);
    } else {
        throw new Error(`API error: ${response.error || 'Unknown error'}`);
    }
};

Best Practices​

1. Check Task Status​

Always check the task_status field to determine if a task is complete:

  • 200: Task completed successfully
  • 100-199: Task in progress or queued
  • 400+: Task failed

2. Handle Pagination​

const getAllReviews = async (taskId, foreignKey, publisherKey) => {
    let allReviews = [];
    let page = 1;
    let hasNext = true;
    
    while (hasNext) {
        const response = await retrieveTask(taskId, foreignKey, publisherKey, page);
        allReviews = allReviews.concat(response.reviews);
        hasNext = response.pagination.has_next;
        page++;
    }
    
    return allReviews;
};

3. Use S3 URLs for Full Data​

For complete datasets, use the reviews_urls field to download full review data from S3.

4. Monitor Error Responses​

Implement proper error handling for different status codes and error types.

Need Help?​

If you encounter unexpected responses:

  1. Test in Playground: Use the interactive playground to test your requests
  2. Check Status Codes: Review the HTTP status codes and task status values
  3. Validate Input: Ensure your request format matches the examples
  4. Contact Support: Email techsupport@shoutaboutus.com for assistance