Custom formulas

Custom formulas let you adjust the relative weight of each signal group in the Locus composite score. Instead of using a fixed scoring profile, you define your own weighting — emphasizing the signals that matter most for your asset class and investment thesis. Formulas are versioned and can be applied to portfolios. When a portfolio has an active formula, all location scores are computed with the formula weights instead of the default composite.

How weights work

Each formula defines a weight for the eight Locus signal groups:

Signal group	Key	Default weight
Business vitality	`business_vitality`	1.0
Population momentum	`population_momentum`	1.0
Demographics	`demographics`	1.0
Economic strength	`economic_strength`	1.0
Development pipeline	`development_pipeline`	1.0
Accessibility	`accessibility`	1.0
Safety & environment	`safety_environment`	1.0
Amenity demand	`amenity_demand`	1.0

Weights are normalized so they sum to 1.0 before scoring. A weight of 2.0 on business_vitality with 1.0 on everything else means business vitality contributes roughly 22% of the final score instead of the default 12.5%.

`GET` `/api/v1/locus/formulas`

Requires session authentication.

List all scoring formulas available to you. This includes system-provided formulas and your custom formulas. Parameters

Name	Type	Required	Description
`asset_class`	string		Filter by asset class (e.g. `qsr`, `retail`, `office`).

Response

{
  "formulas": [
    {
      "id": "f_sys_qsr_v1",
      "name": "QSR Standard",
      "asset_class": "qsr",
      "version": 1,
      "is_system": true,
      "weights_json": {
        "business_vitality": 2.0,
        "population_momentum": 1.5,
        "demographics": 1.5,
        "economic_strength": 1.0,
        "development_pipeline": 0.5,
        "accessibility": 1.5,
        "safety_environment": 1.0,
        "amenity_demand": 1.0
      },
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    },
    {
      "id": "f_custom_abc",
      "name": "Drive-through optimized",
      "asset_class": "qsr",
      "version": 2,
      "is_system": false,
      "weights_json": {
        "business_vitality": 1.0,
        "population_momentum": 1.0,
        "demographics": 2.0,
        "economic_strength": 1.0,
        "development_pipeline": 0.5,
        "accessibility": 3.0,
        "safety_environment": 1.0,
        "amenity_demand": 0.5
      },
      "created_at": "2026-03-15T09:00:00Z",
      "updated_at": "2026-04-10T14:00:00Z"
    }
  ]
}

Field	Type	Description
`is_system`	boolean	`true` for Locus-provided formulas, `false` for your custom formulas.
`weights_json`	object	Signal group weights. Normalized to sum to 1.0 when applied.
`version`	int	Formula version number.

Example

curl https://axiomlocus.io/api/v1/locus/formulas?asset_class=qsr \
  -H "Authorization: Bearer YOUR_TOKEN"

`POST` `/api/v1/locus/formulas`

Requires session authentication.

Create a custom scoring formula. If you omit weights_json, Locus uses the default weights for the specified asset class. Parameters

Name	Type	Required	Description
`name`	string	✓	Formula name.
`asset_class`	string	✓	Asset class this formula is designed for.
`version`	number		Version number (default 1).
`weights_json`	object		Custom weights. Each key is a signal group, value is the relative weight.

Example

curl -X POST https://axiomlocus.io/api/v1/locus/formulas \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Drive-through optimized",
    "asset_class": "qsr",
    "weights_json": {
      "business_vitality": 1.0,
      "demographics": 2.0,
      "accessibility": 3.0,
      "amenity_demand": 0.5
    }
  }'

Response (HTTP 201)

{
  "formula": {
    "id": "f_custom_abc",
    "name": "Drive-through optimized",
    "asset_class": "qsr",
    "version": 1,
    "is_system": false,
    "weights_json": {
      "business_vitality": 1.0,
      "population_momentum": 1.0,
      "demographics": 2.0,
      "economic_strength": 1.0,
      "development_pipeline": 1.0,
      "accessibility": 3.0,
      "safety_environment": 1.0,
      "amenity_demand": 0.5
    },
    "created_at": "2026-04-20T12:00:00Z",
    "updated_at": "2026-04-20T12:00:00Z"
  }
}

Any signal group you omit from weights_json defaults to 1.0. Weights are normalized before scoring so only the ratios between groups matter, not the absolute values.

Compare formulas

`GET` `/api/v1/locus/formulas/compare`

Requires session authentication.

Score a single H3 cell with multiple formulas side-by-side. Use this to see how different weightings affect the composite score for a specific location before applying a formula to your portfolio. Parameters

Name	Type	Required	Description
`h3_index`	string	✓	H3 cell id to score.
`profile`	string		Scoring profile (default `general`).
`formula_ids`	string	✓	Comma-separated formula ids to compare.

Response

{
  "h3_index": "882a100d63fffff",
  "profile": "general",
  "base_composite": 72.0,
  "comparisons": [
    {
      "formula_id": "f_sys_qsr_v1",
      "name": "QSR Standard",
      "asset_class": "qsr",
      "version": 1,
      "is_system": true,
      "score": 76.3,
      "delta_from_base": 4.3
    },
    {
      "formula_id": "f_custom_abc",
      "name": "Drive-through optimized",
      "asset_class": "qsr",
      "version": 2,
      "is_system": false,
      "score": 79.1,
      "delta_from_base": 7.1
    }
  ]
}

Field	Type	Description
`base_composite`	float	Default composite score without any formula.
`comparisons[].score`	float	Composite score using this formula’s weights.
`comparisons[].delta_from_base`	float	Difference from the default composite. Positive means the formula scores this location higher.

Example

curl "https://axiomlocus.io/api/v1/locus/formulas/compare?h3_index=882a100d63fffff&formula_ids=f_sys_qsr_v1,f_custom_abc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Overview

Scoring

Location data

Portfolio management

Reports & exports

Platform

How weights work

`GET` `/api/v1/locus/formulas`

`POST` `/api/v1/locus/formulas`

Compare formulas

`GET` `/api/v1/locus/formulas/compare`

​How weights work

​GET /api/v1/locus/formulas

​POST /api/v1/locus/formulas

​Compare formulas

​GET /api/v1/locus/formulas/compare

How weights work

`GET` `/api/v1/locus/formulas`

`POST` `/api/v1/locus/formulas`

Compare formulas

`GET` `/api/v1/locus/formulas/compare`