Skip to main content
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 groupKeyDefault weight
Business vitalitybusiness_vitality1.0
Population momentumpopulation_momentum1.0
Demographicsdemographics1.0
Economic strengtheconomic_strength1.0
Development pipelinedevelopment_pipeline1.0
Accessibilityaccessibility1.0
Safety & environmentsafety_environment1.0
Amenity demandamenity_demand1.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
NameTypeRequiredDescription
asset_classstringFilter 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"
    }
  ]
}
FieldTypeDescription
is_systembooleantrue for Locus-provided formulas, false for your custom formulas.
weights_jsonobjectSignal group weights. Normalized to sum to 1.0 when applied.
versionintFormula 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
NameTypeRequiredDescription
namestring✓Formula name.
asset_classstring✓Asset class this formula is designed for.
versionnumberVersion number (default 1).
weights_jsonobjectCustom 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
NameTypeRequiredDescription
h3_indexstring✓H3 cell id to score.
profilestringScoring profile (default general).
formula_idsstring✓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
    }
  ]
}
FieldTypeDescription
base_compositefloatDefault composite score without any formula.
comparisons[].scorefloatComposite score using this formula’s weights.
comparisons[].delta_from_basefloatDifference 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"