Action Required: Upcoming breaking changes to MAPEGY.API

On December 1, 2026, MAPEGY.API will introduce two breaking changes: standardized JSON response structures and strict parameter validation.

‍

Quick summary: Why & What you need to do

Why we are making these changes:

• Consistency & extensibility: Aligning response structures enables future metadata additions without disrupting existing payloads.
• Reliability: Stricter parameter validation surfaces naming and type mismatches immediately, a frequent issue when generating queries with LLMs.

What action is required by December 1, 2026:

• Update parsing logic: Update consumers of affected endpoints to unpack the new "data" envelope (a backwards-compatible code pattern is provided below).
• Audit request parameters: Verify all query parameters against our documentation, as invalid parameter names or values will now return explicit errors rather than being ignored.

‍

Detailed overview of changes

Change 1: Aligned response formats

We are standardizing the JSON response format for the following endpoints:

• Autosuggest/Topics
• Autosuggest/Organizations
• Documents
• Facets/Documents/Year
• Facets/Documents/Quarter
• Facets/Documents/Month

Currently, these endpoints return JSON arrays directly:

[item1, item2, ...]

Starting December 1, 2026, they will return JSON objects containing the array within a data property:

{ "data": [item1, item2, ...] }

‍

Implementation guide:

If your integration uses any of the affected endpoints, you will need to adjust how the response data is accessed.

For example, in JavaScript, instead of: const arrayData = parsedJson;

You can use:

const arrayData = Array.isArray(parsedJson) ? parsedJson : parsedJson.data;

This approach is compatible with both the current and the new response formats, allowing you to update your integration ahead of the scheduled change without disrupting existing functionality.

‍

Change 2: Stricter handling of invalid parameters

Previously, unrecognized or invalid function parameters were ignored when possible. Beginning December 1, 2026, passing invalid parameter keys or values will return an error.

For example, a request to the Documents function with type=PATENTS or types=PATENT will fail because the correct parameter is type=PATENT.

Implementation Guide:

If in doubt, check your code and compare the parameters you use with our API documentation.

‍

‍

Please review and update your integrations ahead of December 1, 2026 to ensure continuous operation.

We understand that breaking changes require development effort, and we appreciate your time and proactive cooperation as we improve the reliability and future capabilities of MAPEGY.API.