Name: Percentile Engine API
Brand: nicheapi-llc-1
SKU: api-nicheapi-llc-1-percentileengine
Availability: InStock
Author: API Market

True Scary Stories

# Percentile Engine API

## Overview
The Percentile Engine API lets you compare any measurable trait against population-backed distributions to return an exact percentile, z-score, and plain-English verdict. It covers 34 curated metrics across 9 categories — running, strength, physique, income, lifestyle, cognition, demographics, health, and fun — drawing on 50M+ data points from authoritative sources including the CDC, ACSM, BLS, WHO, NIH, and Running USA. Beyond single-metric analysis, the API offers a combo endpoint that calculates the combined statistical rarity of a multi-metric profile, expressing it as a "1 in N" probability — suited for viral shareable features, fitness apps, health platforms, and recruiting tools.

## Features

*   **34 Metrics Across 9 Categories**: Running (6 metrics), Strength (4), Physique (4), Income (2), Lifestyle (5), Cognition (5), Demographics (2), Health (4), and Fun (2) — each backed by a named authoritative data source.
*   **Percentile & Z-Score Output**: Every analysis returns the submitted value's percentile rank, z-score, population mean, population standard deviation, sample size, and a labeled plain-English verdict.
*   **Combo Rarity Analysis**: Submit multiple metrics simultaneously to calculate the combined probability and "1 in N" rarity of that exact profile across the population.
*   **Age, Sex, and Country Segmentation**: Analysis can be scoped by age, sex (`male`, `female`, or `all`), and country where the underlying data supports it.
*   **50M+ Data Points**: Distributions sourced from CDC NHANES, Running USA, ACSM FRIEND Registry, NSCA/ExRx.net, Bureau of Labor Statistics, Federal Reserve SCF, WAIS-V, and others. Every response includes a `data_source` citation.
*   **Batch Processing**: Analyze multiple metrics in a single request without looping individual calls.
*   **Test Sample Generation**: Generate random test samples with realistic values across metrics for development and schema validation.
*   **High Availability**: Rate limits from 10 req/min (Free) up to 300 req/min (Pro) depending on plan.

## Use Cases

The Percentile Engine API is suited for a range of fitness, health, consumer, and enterprise workflows:

*   **Fitness Apps**: Show users exactly where their 5K time, VO2 max, grip strength, or step count ranks against the population — by age and sex — rather than displaying raw numbers without context.
*   **Health & Wellness Platforms**: Compare biometrics such as HbA1c, blood pressure, HDL cholesterol, and fasting glucose against population norms from CDC NHANES data, giving users clinically grounded context for their results.
*   **HR & Recruiting Tools**: Assess candidate percentiles for typing speed, IQ, years of education, and reaction time against population distributions, providing standardized comparison signals alongside raw scores.
*   **Personal Finance Apps**: Surface salary and net worth percentiles segmented by age, sex, and country using BLS and Federal Reserve data — adding population context to financial dashboards.
*   **Social & Dating Products**: Power "how rare are you?" features using the combo endpoint to calculate multi-metric rarity scores and generate shareable results.
*   **Content & Engagement Features**: Drive viral sharing with combination rarity outputs expressed as "1 in N" statistics across fitness, cognition, and lifestyle dimensions.
*   **Research & Data Visualization**: Retrieve distribution parameters — mean, standard deviation, sample size, and data source — for any of the 34 metrics to power charts, infographics, or academic reference tools.


## API Documentation

### Base URL
All API requests for the Percentile Engine API should be made to the following base URL:
`https://prod.api.market/api/v1/nicheapi-llc-1/percentileengine/v1/percentileengine`

### Authentication
Authentication is handled via an API key obtained from RapidAPI. Include your key in the `x-api-market-key` header of every request:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key from RapidAPI.


### Endpoints

#### 1. Analyze a Single Metric

Submit a single metric value for percentile analysis against population data. Returns the percentile rank, z-score, population distribution parameters, and a plain-English verdict.

**Method**: `POST`
**Endpoint**: `/v1/percentileengine/analyze`

**Request Body**:

| Name | In | Description | Type | Required |
| :--- | :--- | :--- | :--- | :--- |
| `metric` | body | Metric identifier (e.g., `"5k_time"`, `"iq_score"`, `"annual_salary"`). See `/metrics` for the full list. | `string` | Yes |
| `value` | body | The measured value to analyze | `number` | Yes |
| `age` | body | Subject's age in years, used for age-segmented distributions where available | `integer` | No |
| `sex` | body | Subject's sex for sex-segmented distributions: `"male"`, `"female"`, or `"all"` | `string` | No |
| `country` | body | Country code for country-segmented metrics (e.g., `"US"`, `"global"`) | `string` | No |

**Example Request**:

```bash
curl -X POST "https://prod.api.market/api/v1/nicheapi-llc-1/percentileengine/v1/percentileengine/analyze" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "5k_time",
    "value": 22.5,
    "age": 32,
    "sex": "male",
    "country": "global"
  }'
```

**Example Response (200 OK)**:

```json
{
  "metric": "5k_time",
  "metric_name": "5K Run Time (Men)",
  "your_value": "22:30 /5K",
  "unit": "minutes",
  "age": 32,
  "sex": "male",
  "country": "global",
  "percentile": 62.1,
  "z_score": -0.31,
  "population_mean": 24.2,
  "population_sd": 5.5,
  "higher_is_better": false,
  "label": "60",
  "rank_word": "top 40%",
  "sample_size": 15000000,
  "verdict": "Your 22:30 /5K 5K Run Time is above average (top 40%) among male age 32.",
  "data_source": "Running USA Age-Graded Tables, Parkrun 2024"
}
```

#### 2. Batch Analyze Metrics

Analyze multiple metrics in a single request. Each query in the batch can specify its own metric, value, age, sex, and country parameters.

**Method**: `POST`
**Endpoint**: `/v1/percentileengine/analyze/batch`

**Request Body**:

| Name | In | Description | Type | Required |
| :--- | :--- | :--- | :--- | :--- |
| `queries` | body | Array of metric query objects, each following the same structure as the `/analyze` request body | `array` | Yes |

**Example Request**:

```bash
curl -X POST "https://prod.api.market/api/v1/nicheapi-llc-1/percentileengine/v1/percentileengine/analyze/batch" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"metric": "5k_time", "value": 22.5, "age": 32, "sex": "male"},
      {"metric": "iq_score", "value": 130, "age": 30, "sex": "all"}
    ]
  }'
```

#### 3. Combo Rarity Analysis

Calculate the combined statistical rarity of a multi-metric profile. Returns the joint probability expressed as a decimal, a "1 in N" integer, and a human-readable string alongside per-metric percentile breakdowns.

**Method**: `POST`
**Endpoint**: `/v1/percentileengine/combo`

**Request Body**:

| Name | In | Description | Type | Required |
| :--- | :--- | :--- | :--- | :--- |
| `metrics` | body | Array of metric query objects to combine, each following the same structure as the `/analyze` request body | `array` | Yes |

**Example Request**:

```bash
curl -X POST "https://prod.api.market/api/v1/nicheapi-llc-1/percentileengine/v1/percentileengine/combo" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      {"metric": "5k_time", "value": 19.5, "age": 30, "sex": "male"},
      {"metric": "typing_wpm", "value": 95, "age": 30, "sex": "male"},
      {"metric": "iq_score", "value": 130, "age": 30, "sex": "male"}
    ]
  }'
```

**Example Response (200 OK)**:

```json
{
  "combined_probability": 4.76e-9,
  "one_in_n": 210039908,
  "readable": "1 in 210.0 million",
  "total_metrics": 3,
  "details": [
    {"metric": "5k_time", "value": 19.5, "percentile": 79.3, "label": "70", "rank_word": "top 30%"},
    {"metric": "typing_wpm", "value": 95, "percentile": 100, "label": "99+", "rank_word": "top 1%"},
    {"metric": "iq_score", "value": 130, "percentile": 97.7, "label": "95", "rank_word": "top 5%"}
  ]
}
```

#### 4. Run Test Scenarios

Generate random test samples with realistic values across available metrics for development and schema validation.

**Method**: `POST`
**Endpoint**: `/v1/percentileengine/test`

**Request Body**:

| Name | In | Description | Type | Required | Default |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `count` | body | Number of random test samples to generate | `integer` | No | `1` |

**Example Request**:

```bash
curl -X POST "https://prod.api.market/api/v1/nicheapi-llc-1/percentileengine/v1/percentileengine/test" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 3}'
```

#### 5. List Metrics

Retrieve all 34 available metrics with their categories, units, supported segmentation (age, sex, country), and data source citations.

**Method**: `GET`
**Endpoint**: `/v1/percentileengine/metrics`

**Parameters**:

| Name | In | Description | Type | Required | Default | Max Value |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| `q` | query | Search query to filter metrics by keyword or category | `string` | No | | |
| `limit` | query | Maximum number of results | `integer` | No | `50` | `1000` |
| `offset` | query | Number of results to skip for pagination | `integer` | No | `0` | |

**Example Request**:

```bash
curl -X GET "https://prod.api.market/api/v1/nicheapi-llc-1/percentileengine/v1/percentileengine/metrics" \
  -H "x-api-market-key: YOUR_API_KEY"
```


## Status Codes
Below is a list of common HTTP status codes you may encounter when interacting with the Percentile Engine API:

*   **`200 OK`**: The request was successful and the server has returned the requested data.
*   **`400 Bad Request`**: The server could not process the request due to invalid input — such as a missing `metric` or `value` field, an unrecognized metric identifier, an out-of-range value for the specified metric, or an invalid `sex` value. Use the `/metrics` endpoint to verify valid metric identifiers before submitting. Review your request body before retrying.
*   **`401 Unauthorized`**: Authentication failed. Your `x-api-market-key` header is missing or contains an invalid key. Confirm your key is active and correctly included in the request header.
*   **`403 Forbidden`**: Your API key is valid, but the requested endpoint is not available on your current plan. The `/combo` and `/test` endpoints require Pro tier or above. Review your plan's permissions on RapidAPI.
*   **`404 Not Found`**: The requested endpoint does not exist. Verify the URL path against the endpoint reference above, noting that all endpoints use the `/v1/percentileengine/` prefix.
*   **`429 Too Many Requests`**: You have exceeded your plan's rate limit. Implement client-side rate limiting and exponential backoff. Check the `Retry-After` response header for guidance on when to retry.
*   **`500 Internal Server Error`**: An unexpected server-side error occurred. Retry the request after a short delay.
*   **`503 Service Unavailable`**: The server is temporarily unavailable due to maintenance or elevated load. Retry after a short delay.

## Rate Limits

Rate limits vary by plan:

| Plan | Price | Requests/Month | Rate Limit |
| :--- | :--- | :--- | :--- |
| **Free** | $0 | 100 | 10 req/min |
| **Starter** | $29/mo | 5,000 | 60 req/min |
| **Pro** | $99/mo | 50,000 | 300 req/min |
| **Enterprise** | Custom | Unlimited | Custom |

If you exceed your plan's rate limit, the API returns a `429 Too Many Requests` status code. Implement exponential backoff in your client and monitor the `Retry-After` header for retry timing guidance.

## FAQ

*   **How do I know which metric identifiers to use?**
    Call `GET /v1/percentileengine/metrics` to retrieve the full list of 34 metric identifiers with their categories, units, and data source citations. Pass the identifier string exactly as returned in the `metric` field of your `/analyze` or `/combo` request.

*   **What do the `percentile` and `z_score` fields represent?**
    The `percentile` is the percentage of the reference population that scored at or below the submitted value (adjusted for `higher_is_better` direction). The `z_score` is the number of standard deviations the submitted value sits above or below the population mean for the specified age, sex, and country segment.

*   **Does the API account for age and sex differences in distributions?**
    Yes, where the underlying data supports it. Include `age` and `sex` in your request to receive a segmented result. If segmentation is not available for a given metric, the API falls back to an unsegmented population distribution and notes this in the response.

*   **How does the combo endpoint calculate combined rarity?**
    The `/combo` endpoint multiplies the individual percentile probabilities of each submitted metric to produce a joint probability, expressed as `combined_probability`, `one_in_n`, and a human-readable `readable` string. This assumes independence between metrics, which is an approximation — correlated traits (e.g., height and weight) will produce a more extreme rarity figure than the true joint probability.

*   **Which endpoints are restricted by plan?**
    The Free plan provides access to `GET /metrics` only. The Starter plan unlocks `/analyze` and `/analyze/batch`. The `/combo` and `/test` endpoints require Pro tier or above. Enterprise plans include full access plus custom metrics and dedicated infrastructure.

*   **How do I authenticate my requests?**
    All requests require an `x-api-market-key` header with your API key obtained from RapidAPI.

*   **What is the rate limit for my plan?**
    Rate limits range from 10 requests/minute on Free to 300 requests/minute on Pro, with custom limits for Enterprise. See the Rate Limits section for the full breakdown.

## Contact Us

If you have any questions or need assistance, you can reach out through the embedded chat on the bottom right corner of the page or send an email to 21truescarystories@gmail.com.

The Percentile Engine API lets you compare any measurable trait, fitness, physique, income, cognition, lifestyle, health, and more,against population-backed 