> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axiomancer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Scoring

> Score any latitude and longitude across eight Locus signal groups with configurable scoring profiles for QSR, retail, office, industrial, and more.

## `GET` `/api/score`

Score a location across all 8 signal groups.

**Query parameters**

| Name      | Type   | Required | Default   | Description                                                                                                            |
| --------- | ------ | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `lat`     | float  | ✓        |           | Latitude of the location.                                                                                              |
| `lng`     | float  | ✓        |           | Longitude of the location.                                                                                             |
| `radius`  | float  |          | `1.0`     | Radius in km (max 10).                                                                                                 |
| `profile` | string |          | `general` | Scoring profile. One of: `general`, `qsr`, `self_storage`, `retail`, `office`, `data_center`, `industrial`.            |
| `include` | string |          |           | Comma-separated extras: `uncertainty`, `esgi`. Adds uncertainty quantification or Pioneer Signal data to the response. |

**Example**

```bash theme={null}
curl "https://axiomlocus.io/api/score?lat=37.7749&lng=-122.4194"
```

**Response**

```json theme={null}
{
  "composite": 78.4,
  "confidence": 0.92,
  "sourcesUsed": 36,
  "sourcesTotal": 43,
  "metro": "sf",
  "profile": "general",
  "groups": {
    "businessVitality": {
      "score": 82.1,
      "confidence": 1.0,
      "sourcesActive": 5,
      "sourcesTotal": 6,
      "subScores": [
        { "name": "Net Business Openings", "score": 71 },
        { "name": "Category Diversity", "score": 88 },
        { "name": "Rating Trajectory", "score": 79 }
      ]
    }
  }
}
```

| Field          | Type   | Description                                                                                    |
| -------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `composite`    | float  | Overall score from 0 to 100.                                                                   |
| `confidence`   | float  | Data completeness ratio from 0.0 to 1.0.                                                       |
| `sourcesUsed`  | int    | Number of data sources that returned data.                                                     |
| `sourcesTotal` | int    | Total possible data sources.                                                                   |
| `metro`        | string | Metro slug where the location was resolved.                                                    |
| `profile`      | string | Scoring profile used.                                                                          |
| `groups`       | object | Per-signal-group breakdown with score, confidence, sourcesActive, sourcesTotal, and subScores. |

## `POST` `/api/bulk-score`

<Note>Requires Bearer token.</Note>

Score up to 50 locations in a single request.

**Request body**

```json theme={null}
{
  "locations": [
    { "lat": 37.7749, "lng": -122.4194 },
    { "lat": 34.0522, "lng": -118.2437 }
  ],
  "radius": 1.0,
  "profile": "qsr"
}
```

| Field       | Type   | Required | Default   | Description                                                                                                                   |
| ----------- | ------ | -------- | --------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `locations` | array  | ✓        |           | Array of { lat, lng } objects. Maximum 50.                                                                                    |
| `radius`    | float  |          | `1.0`     | Radius in km (max 10). Applied to all locations.                                                                              |
| `profile`   | string |          | `general` | Scoring profile for all locations. One of: `general`, `qsr`, `self_storage`, `retail`, `office`, `data_center`, `industrial`. |

**Example**

```bash theme={null}
curl -X POST "https://axiomlocus.io/api/bulk-score" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"locations":[{"lat":37.77,"lng":-122.41},{"lat":34.05,"lng":-118.24}]}'
```

**Response**

```json theme={null}
{
  "results": [
    {
      "lat": 37.77,
      "lng": -122.41,
      "composite": 78.4,
      "confidence": 0.92,
      "groups": { "..." : "..." }
    },
    {
      "lat": 34.05,
      "lng": -118.24,
      "composite": 71.2,
      "confidence": 0.88,
      "groups": { "..." : "..." }
    }
  ]
}
```

| Field                  | Type   | Description                                     |
| ---------------------- | ------ | ----------------------------------------------- |
| `results`              | array  | Array of score objects, one per input location. |
| `results[].composite`  | float  | Composite score (0-100) for the location.       |
| `results[].confidence` | float  | Data completeness ratio.                        |
| `results[].groups`     | object | Signal group breakdown.                         |