Guides
Start typing to search…

Publisher Model

The Publisher model defines the configuration for each review platform from which reviews will be collected.

Schema

{
  "profile_key": "string",
  "last_review_hashes": ["string"],
  "first_page_only": "boolean",
  "persona": {
    "additional_cookies": {
      "login": [
        {
          "name": "string",
          "value": "string",
          "domain": "string"
        }
      ]
    }
  }
}

Fields

Request Fields
Field Type Required Description
profile_key string Yes Business URL/ID at publisher
last_review_hashes array Yes Hashes from previous reviews
first_page_only boolean Yes true = first page, false = all pages
persona object No Additional configuration for specific publishers
🚧

IMPORTANT REQUEST LIMITATIONS

Each API request can only target ONE review platform at a time.

This means:

  • ✅ Single request: Get reviews from Google Maps for McDonald's
  • ❌ NOT allowed: Get reviews from Google Maps + Yelp + TripAdvisor for McDonald's in one request

For multiple platforms, submit separate requests:

  • Request 1: McDonald's reviews from Google Maps
  • Request 2: McDonald's reviews from Yelp
  • Request 3: McDonald's reviews from TripAdvisor

Example: If you want review data from 5 different platforms (Google Maps, Yelp, TripAdvisor, Facebook, etc.) for the same business location, you must submit 5 separate API requests.

📘

PROFILE KEY COST INFORMATION

**What is a Profile Key? **The profile_key is the direct URL to your business on a review platform (e.g., your Google Maps listing URL, Yelp business page URL).

Cost Impact:

  • ✅ Provide the profile_key: Standard pricing (you pay only for review data extraction)
  • ❌ Don't provide profile_key: Standard pricing + extra business search fee

How it works:

  • ✅ With profile_key: You give us the exact business URL → We extract reviews → You pay standard rate
  • ❌ Without profile_key: You give us business name/address → We find your business URL → We extract reviews → You pay standard rate + search fee

💰 Save Money: Always include the profile_key in your requests and save it for future use to avoid the additional search costs.

Field Details

Profile Key

  • Type: string (URI format)
  • Required: Yes
  • Description: The URL or identifier for the business on the specific publisher platform
  • Examples:
    • Google Maps: https://www.google.com/maps/place/Business-Name/@lat,lng,17z/
    • Yelp: https://www.yelp.com/biz/business-name
    • TripAdvisor: https://www.tripadvisor.com/Restaurant_Review-g12345-d123456-Reviews-Business_Name-City_State.html

Last Review Hashes

  • Type: array of strings
  • Required: Yes
  • Description: Array of review hashes from previously collected reviews to prevent duplicates
  • Format: MD5 or SHA256 hashes
  • Examples: ["9487e4202954d101e15e95cc06a8c4e8", "6bb1a0e4195079f58506c60633cb20cc"]

First Page Only

  • Type: boolean
  • Required: Yes
  • Description: Controls whether to collect only the first page of reviews or all available pages
  • Values:
    • true: Collect only the first page (faster, fewer reviews)
    • false: Collect all available pages (slower, more comprehensive)

Persona Object

  • Type: object
  • Required: No
  • Description: Additional configuration for publishers that require authentication or special handling

Additional Cookies

  • Type: object
  • Description: Cookies required for accessing certain publishers (e.g., Facebook, Yelp)
  • Structure: Key-value pairs where keys are cookie categories

Login Cookies

  • Type: array of cookie objects
  • Description: Authentication cookies for logged-in access
  • Required for: Facebook, Yelp, and other platforms requiring authentication

Cookie Object

{
  "name": "string",
  "value": "string",
  "domain": "string"
}
Cookie Fields
Field Type Required Description
name string Yes Cookie name
value string Yes Cookie value
domain string Yes Cookie domain

Examples

{
  "profile_key": "https://www.google.com/maps/place/McDonald's/@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=EgoyMDI1MDYyMi4wIKXMDSoASAFQAw%3D%3D",
  "last_review_hashes": [
    "9487e4202954d101e15e95cc06a8c4e8",
    "6bb1a0e4195079f58506c60633cb20cc"
  ],
  "first_page_only": false
}

Google Maps (maps.google.com)

  • Profile Key: Full Google Maps business URL with coordinates
  • Special Features: Automatic geolocation support
  • Rate Limits: Standard limits apply
  • Authentication: Not required

Usage in API Requests

The Publisher model is used within the publishers object in the request payload:

{
  "job": "App\\Jobs\\RequestReviews",
  "data": {
    "api_key": "your-api-key",
    "foreign_key": "12345",
    "lazy": true,
    "business": {
      // ... business data
    },
    "publishers": {
      "maps.google.com": {
        "profile_key": "https://www.google.com/maps/place/Business/@lat,lng,17z/",
        "last_review_hashes": ["hash1", "hash2"],
        "first_page_only": false
      }
    }
  }
}
Best Practices

  • Profile Key

    • Accuracy: Ensure the profile key points to the correct business
    • Format: Use the exact URL format expected by each publisher
    • Verification: Test profile keys manually before submitting requests
    • Updates: Keep profile keys current as business URLs may change

  • Review Hashes

    • Storage: Maintain a database of collected review hashes
    • Updates: Update hashes after successful collection
    • Deduplication: Use hashes to prevent collecting duplicate reviews
    • Format: Use consistent hash algorithms across your system

  • First Page Only

    • Use Cases: Set to true for quick checks or limited data needs
    • Comprehensive: Set to false for complete review collection
    • Performance: Consider processing time and rate limits
    • Cost: May affect API usage and costs

  • Authentication

    • Security: Store authentication cookies securely
    • Rotation: Regularly update authentication credentials
    • Monitoring: Monitor for authentication failures
    • Fallback: Have backup authentication methods when possible
Validation Rules

  • Profile Key

    • Format: Valid URI
    • Length: 1-2000 characters
    • Protocol: HTTPS recommended
    • Domain: Must match publisher domain

  • Last Review Hashes

    • Format: Array of strings
    • Length: 0-1000 hashes
    • Hash Format: MD5 or SHA256
    • Uniqueness: Each hash should be unique

  • First Page Only

    • Type: Boolean
    • Default: false
    • Usage: Controls pagination behavior

  • Additional Cookies

    • Format: Valid cookie objects
    • Security: Sensitive data, handle with care
    • Expiration: Monitor cookie expiration
    • Validation: Verify cookie format and domain
Error Handling

  • Common Issues

    1. Invalid Profile Key: 400 Bad Request
    2. Authentication Required: 401 Unauthorized
    3. Rate Limiting: 429 Too Many Requests
    4. Business Not Found: 404 Not Found

  • Troubleshooting

    • Verify profile key accuracy
    • Check authentication credentials
    • Monitor rate limits
    • Validate cookie formats

Updated 2 months ago