World map

The /reports/map endpoint returns a geographic breakdown of customers and MRR by country, including key metrics per country. This is ideal for building geographic visualizations and understanding regional performance.

💡 Use case: Build interactive maps, analyze regional performance, identify expansion opportunities, compare metrics across countries.

GET /reports/map

Returns country-level metrics for geographic analysis.

Authentication

Required

Include your API key in the Authorization header:

curl https://api.growpanel.io/reports/map \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

Parameter	Type	Description
`date`optional	string	Date range. Format: `YYYYMMDD-YYYYMMDD` or shortcuts.
`baseCurrency`optional	string	Target currency for conversion. Defaults to account base currency.
`sort`optional	string	Sort field. Defaults to `current_mrr`.
`order`optional	string	Sort direction: `asc` or `desc`. Defaults to `desc`.
`fix_fx`optional	boolean	Use fixed exchange rates.
`region`optional	string	Filter by region or country codes (space-separated).
`currency`optional	string	Filter by currency codes (space-separated).
`industry`optional	string	Filter by industry (space-separated).
`channel`optional	string	Filter by channel (space-separated).
`size`optional	string	Filter by customer size (space-separated).
`data_source`optional	string	Filter by data source ID (space-separated).

Response

200 OK

Returns metrics grouped by country (ISO 3166-1 alpha-2 codes).

{
  "result": {
    "list": {
      "US": {
        "current_mrr": 65000,
        "subscribers": 120,
        "arpa": 542,
        "asp": 800,
        "customer_churn_rate": 0.03,
        "net_mrr_churn": -0.01,
        "ltv": 18000,
        "leads": 200,
        "leads_converted": 50,
        "lead_conversion_rate": 25.0,
        "new_trials": 80,
        "trials_converted": 40,
        "trial_conversion_rate": 50.0,
        "payment_failure_rate": 2.5,
        "mrr_percent": 52.0,
        "subscribers_percent": 48.0,
        "leads_percent": 40.0,
        "trials_percent": 42.1
      },
      "DE": {
        "current_mrr": 25000,
        "subscribers": 60,
        "arpa": 417,
        "asp": 600,
        "customer_churn_rate": 0.02,
        "net_mrr_churn": 0.005,
        "ltv": 20850,
        "leads": 100,
        "leads_converted": 30,
        "lead_conversion_rate": 30.0,
        "new_trials": 50,
        "trials_converted": 25,
        "trial_conversion_rate": 50.0,
        "payment_failure_rate": 1.8,
        "mrr_percent": 20.0,
        "subscribers_percent": 24.0,
        "leads_percent": 20.0,
        "trials_percent": 26.3
      }
    }
  }
}

Response fields (per country)

Field	Type	Description
Revenue Metrics
`current_mrr`	number	MRR in base currency (cents)
`subscribers`	integer	Active subscriber count
`arpa`	number	Average revenue per account (cents)
`asp`	number	Average subscription price (cents)
Retention Metrics
`customer_churn_rate`	float	Customer churn rate (decimal, e.g., 0.03 = 3%)
`net_mrr_churn`	float	Net MRR churn rate (decimal)
`ltv`	number	Customer lifetime value (cents)
Lead Metrics
`leads`	integer	Total leads
`leads_converted`	integer	Leads converted to paid
`lead_conversion_rate`	float	Lead conversion rate (percentage)
Trial Metrics
`new_trials`	integer	Total new trials
`trials_converted`	integer	Trials converted to paid
`trial_conversion_rate`	float	Trial conversion rate (percentage)
Other Metrics
`payment_failure_rate`	float	Payment failure rate (percentage)
Distribution Percentages
`mrr_percent`	float	Percentage of total MRR
`subscribers_percent`	float	Percentage of total subscribers
`leads_percent`	float	Percentage of total leads
`trials_percent`	float	Percentage of total trials

Example requests

Get geographic distribution

curl https://api.growpanel.io/reports/map \
  -H "Authorization: Bearer YOUR_API_KEY"

Sort by subscriber count

curl "https://api.growpanel.io/reports/map?sort=subscribers&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by region

curl "https://api.growpanel.io/reports/map?region=eu" \
  -H "Authorization: Bearer YOUR_API_KEY"

Compare specific countries

curl "https://api.growpanel.io/reports/map?region=us gb de" \
  -H "Authorization: Bearer YOUR_API_KEY"

Notes

⚠️ Currency values: All monetary values are returned in cents/smallest currency unit. Divide by 100 for display in most currencies.

Country codes: Uses ISO 3166-1 alpha-2 codes (e.g., US, GB, DE)
Geographic source: Based on customer billing address from your billing system
Percentage totals: Distribution percentages show each country's share of the total
Missing countries: Countries with zero customers/MRR are not included in response
Sorting: Default sort is by current_mrr descending (highest revenue first)

Summary Metrics - Overall metric snapshots
MRR Table - Time-series with country breakdown
Customer Concentration - Revenue concentration analysis