# Regions

Endpoints for analyzing AI vulnerability at the metropolitan statistical area (MSA) level.

**Access:** Professional, Enterprise

## List Regions

```http
GET /regions
```

List all MSA regions with aggregate risk metrics.

### Parameters

| Parameter        | Type   | Required | Default      | Description                             |
| ---------------- | ------ | -------- | ------------ | --------------------------------------- |
| `state`          | string | No       | -            | Filter by state code (e.g., "CA", "TX") |
| `min_employment` | int    | No       | 0            | Minimum total employment                |
| `sort_by`        | string | No       | `employment` | Sort field                              |
| `limit`          | int    | No       | 50           | Max results (1-500)                     |

### Response

```json
{
  "count": 31,
  "regions": [
    {
      "msa_code": "31080",
      "msa_name": "Los Angeles-Long Beach-Anaheim, CA",
      "total_employment": 4523000,
      "total_at_risk_wages": 12400000000,
      "total_at_risk_jobs": 892000,
      "mean_automation_score": 52.3,
      "mean_resilience_score": 48.7
    }
  ]
}
```

### Examples

```bash
# Get top 20 metros by employment
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/regions?limit=20&sort_by=employment"

# Get California metros
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/regions?state=CA&limit=50"

# Get metros with 500k+ employment, sorted by automation score
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/regions?min_employment=500000&sort_by=mean_automation_score"
```

***

## Get Region Detail

```http
GET /regions/{msa_code}
```

Get detailed risk profile for a specific region.

### Path Parameters

| Parameter  | Type   | Description                      |
| ---------- | ------ | -------------------------------- |
| `msa_code` | string | 5-digit MSA code (e.g., "31080") |

### Query Parameters

| Parameter      | Type | Required | Default | Description                 |
| -------------- | ---- | -------- | ------- | --------------------------- |
| `include_jobs` | bool | No       | `false` | Include job-level breakdown |
| `job_limit`    | int  | No       | 20      | Max jobs to include (1-100) |

### Response (Basic)

```json
{
  "msa_code": "31080",
  "msa_name": "Los Angeles-Long Beach-Anaheim, CA",
  "summary": {
    "total_employment": 4523000,
    "total_at_risk_wages": 12400000000,
    "total_at_risk_jobs": 892000,
    "total_high_risk_jobs": 234000,
    "mean_automation_score": 52.3,
    "mean_resilience_score": 48.7
  }
}
```

### Response (With Jobs)

```json
{
  "msa_code": "31080",
  "msa_name": "Los Angeles-Long Beach-Anaheim, CA",
  "summary": {
    "total_employment": 4523000,
    "total_at_risk_wages": 12400000000,
    "total_at_risk_jobs": 892000,
    "total_high_risk_jobs": 234000,
    "mean_automation_score": 52.3,
    "mean_resilience_score": 48.7
  },
  "top_exposed_jobs": [
    {
      "soc_code": "43-3031.00",
      "title": "Bookkeeping, Accounting, and Auditing Clerks",
      "employment": 78000,
      "mean_annual_wage": 48500,
      "at_risk_wages": 1200000000,
      "at_risk_jobs": 35000,
      "automation_susceptibility_score": 49.3,
      "human_centric_resilience_score": 49.3,
      "balanced_impact_score": 0
    }
  ],
  "top_resilient_jobs": [
    {
      "soc_code": "29-1141.00",
      "title": "Registered Nurses",
      "employment": 112000,
      "mean_annual_wage": 95200,
      "automation_susceptibility_score": 47.3,
      "human_centric_resilience_score": 69.9,
      "balanced_impact_score": 22.6
    }
  ]
}
```

### Examples

```bash
# Get LA region summary
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/regions/31080"

# Get LA region with top 50 jobs
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/regions/31080?include_jobs=true&job_limit=50"
```

***

## Available MSA Codes

Regional data currently covers 31 California metropolitan areas. Top MSAs by employment:

| MSA Code | Metro Area                               |
| -------- | ---------------------------------------- |
| 31084    | Los Angeles-Long Beach-Glendale, CA      |
| 11244    | Anaheim-Santa Ana-Irvine, CA             |
| 40140    | Riverside-San Bernardino-Ontario, CA     |
| 41740    | San Diego-Chula Vista-Carlsbad, CA       |
| 36084    | Oakland-Fremont-Berkeley, CA             |
| 41940    | San Jose-Sunnyvale-Santa Clara, CA       |
| 41884    | San Francisco-San Mateo-Redwood City, CA |
| 40900    | Sacramento-Roseville-Folsom, CA          |
| 23420    | Fresno, CA                               |
| 12540    | Bakersfield-Delano, CA                   |

***

## Response Field Definitions

### Summary Fields

| Field                   | Description                                           |
| ----------------------- | ----------------------------------------------------- |
| `total_employment`      | Total workers in the MSA                              |
| `total_at_risk_wages`   | Annual wages in high-exposure occupations             |
| `total_at_risk_jobs`    | Workers in high-exposure occupations                  |
| `total_high_risk_jobs`  | Workers in very high exposure (balanced impact < -10) |
| `mean_automation_score` | Employment-weighted average automation susceptibility |
| `mean_resilience_score` | Employment-weighted average human resilience          |

### Job Fields

| Field              | Description                                    |
| ------------------ | ---------------------------------------------- |
| `employment`       | Workers in this occupation in this MSA         |
| `mean_annual_wage` | Average annual wage for this occupation in MSA |
| `at_risk_wages`    | Total wages x risk factor                      |
| `at_risk_jobs`     | Employment x risk factor                       |

***

## Use Cases

### Find High-Risk Regions

```bash
# Get regions with highest automation exposure
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/regions?sort_by=mean_automation_score&limit=20"
```

### Compare Regions

```bash
# Get multiple regions for comparison
for msa in 31080 35620 16980; do
  curl -H "Authorization: Bearer $API_KEY" \
    "https://api.maidenlabs.tools/regions/$msa"
done
```

### Regional Investment Analysis

```bash
# Find metros with high at-risk wages for transition investment
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/regions?sort_by=total_at_risk_wages&limit=20&min_employment=100000"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maidenlabs.tools/api-reference/regions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.