Version 2

Version 2 introduces locale output format standardization and new response metadata for review language filtering transparency. This changelog documents the key API changes and differences between V1 and V2.

Locale code format: underscored to dashed

V2 standardizes all locale codes in API responses to use the dashed format (BCP 47), replacing the underscored format used in V1.

This affects the language field on all translation objects (names, descriptions, addresses, and other translated content arrays).

Example — V1 response:

{
  "names": [
    {"language": "es_MX", "value": "El Bistró de Locale", "primary": false}
  ]
}

Example — V2 response:

{
  "names": [
    {"language": "es-MX", "value": "El Bistró de Locale", "primary": false}
  ]
}

📘

Migration note: If your integration parses or matches on the language field in translation objects, update your code to expect dashed locale codes (e.g. es-MX instead of es_MX) when using V2. The locale query parameter accepts dashed format in both V1 and V2.

language_meta object on reviews responses

V2 adds a language_meta metadata object to the reviews endpoint response. This object provides transparency into how language filtering interacts with your review pool, specifically, how many reviews exist in your pool vs. how many matched your language filter.

Response structure:

{
  "data": [ ... ],
  "pagination": { ... },
  "language_meta": {
    "requested_language": "fr",
    "total_in_pool": 25,
    "matched_language": 8,
    "pool_definition": "recent_count"
  }
}

Field reference:

When language_meta appears:

• Present when a language filter is active (from the language query parameter or your delivery configuration).
• Omitted when no language filter is applied.

Example scenarios:

For more context on how the review pool works and how language filtering interacts with it, see the Supported Languages for Reviews guide.