Developer Documentation

Developer API Reference

Integrate purchasing power parity optimization models directly into your SaaS checkout, landing pages, or mobile apps.

Authentication

The API uses dynamic token authentication. You must pass your private Developer API Key inside the request header. Alternatively, you can pass it as a query parameter (though headers are highly recommended for security).

Preferred Header Method x-api-key: gp_live_yourkeyhere

Fallback Query Method ?api_key=gp_live_yourkeyhere

API access requires an active Pro Subscription. You can generate and rotate your keys within the Account Settings dashboard.

Optimize Local Prices

GET /api/v1/optimize

Retrieves localized calculations for all 180+ supported countries optimized by the specified pricing methodology.

Query Parameters

Parameter	Type	Required	Description
basePrice	number	Yes	The base product price in USD to optimize. Must be greater than 0. (Can also pass `amount` ).
method	string	No	Optimization strategy. Options: `ppp` (Default) - Purchasing Power Parity `exchange` - Direct Exchange Rates `minWage` - Minimum Wage Parity `avgSalary` - Average Salary Parity `medianIncome` - Median Income Parity

Rate Limiting & Quotas

To ensure high availability and prevent abuse, request thresholds and quotas are dynamically evaluated:

Rate Limit Threshold Your account is limited to exactly 1 request per second . Exceeding this limit will cause the API to instantly return an HTTP Status code of 429 Too Many Requests .

Monthly Request Quota Lifetime Pro accounts include a generous allowance of 1,000 API requests per month. It is designed for cached integrations and low-frequency updates. This quota is currently experimental as we analyze real-world checkout traffic, and we plan to adjust it upward based on usage analytics and developer feedback to ensure your integrations remain fully covered.

HTTP Response Codes

Status	Title	Details / Resolution
200	OK	The request was successful and localized pricing calculations are returned.
400	Bad Request	Invalid query inputs (e.g. missing `basePrice` or unsupported `method` value).
401	Unauthorized	API Key is missing from the query params or the `x-api-key` headers.
403	Forbidden	The API key provided is invalid or belongs to an account without active premium subscription permissions.
429	Too Many Requests	You are making more than 1 request per second. Please introduce client-side throttling or queuing on your backend.
500	Internal Server Error	An unexpected internal server exception occurred. Please try again later.

Integration Snippets

Example JSON Response

{
  "basePrice": 29,
  "method": "ppp",
  "results": [
    {
      "country": "Brazil",
      "currency": "BRL",
      "localPrice": 78.43,
      "usdPrice": 14.85,
      "changePercent": -49,
      "pppConversionFactor": 2.70
    },
    {
      "country": "India",
      "currency": "INR",
      "localPrice": 696.00,
      "usdPrice": 8.35,
      "changePercent": -71,
      "pppConversionFactor": 24.00
    }
  ]
}