API reference

Authenticating

Every request carries a key as a bearer token. Keys are created in Settings, shown once, and stored as a hash, so a lost key is replaced rather than recovered.

Keys begin ml_test_ or ml_live_, and carry scopes. A resolve needs the resolve scope and nothing more. Give an integration the narrowest set that does its job.

A test key is the same engine with the meters off: it resolves against your published configuration through the same code, is never billed or counted against your plan, and rate limits separately, so developing cannot starve production. Build againstml_test_, swap the key to go live.

Deciding an address

Send an address or a coordinate. An address is geocoded first. A coordinate is used as given, which is what makes an answer reproducible.

curl https://api.maplogics.com/v1/resolve \
  -H "Authorization: Bearer ml_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "line1": "2 E Main St",
      "city": "Richmond",
      "region": "VA",
      "postal_code": "23219",
      "country": "US"
    },
    "context": { "service": "hvac" }
  }'

{
  "request_id": "req_9039f987",
  "status": "resolved",
  "reason_code": "ASSIGNMENT_RULE_MATCHED",
  "serviceable": true,
  "territory": { "id": "trr_...", "name": "Richmond Central" },
  "location":  { "id": "loc_...", "name": "Richmond Central" },
  "outputs": {},
  "ruleset_version": "cfg_01M0X5..."
}

Unserviceable is a 200. The question was answered and the answer was no. A non-2xx means we could not answer, which is a different thing and usually your retry.

Try it from here

Paste a test key and send a real request to the API from this page. Test keys work from the documentation without any origin setup, resolve against your published configuration, and are never billed or metered. A live key is refused from a browser unless its origin is allow-listed, which is the point of live keys.

The key stays in this page's memory and goes only to the API, in the same header your code will send. Nothing here stores it.

From an AI agent

The same decisions are offered as tools over the Model Context Protocol athttps://api.maplogics.com/mcp, with the same key in the same header. Claude and other MCP clients can check an address, check a coordinate and explain a decision. TheMCP guide has the setup for each client.

Reason codes

Branch on reason_code, never on message. The message is written for a person and will be reworded; the code is the contract.

Never collapse these into a boolean. "No territory covers this address", "a territory covers it but nobody can do the work", and "two territories tie" have three different remedies. A single false throws away the one thing that tells you which.

Errors

Every error carries a stable code, the same request_id as the response header, and a message for a person.

Webhooks

Rather than polling for changes, subscribe. We send a signed POST when a configuration goes live, when one is rolled back, and when a location is archived.

Each delivery carries X-MapLogics-Signature: t=<unix>,v1=<hex>. Verify it before trusting the body: your endpoint is public, and without the check anyone who learns the URL can tell you your routing changed.

import crypto from 'node:crypto'

// The timestamp is inside the signed material, so it cannot be
// edited to make an old body look current.
export function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.trim().split('=')),
  )
  const age = Math.abs(Date.now() / 1000 - Number(parts.t))
  if (age > 300) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex')

  // Constant time: comparing with === leaks where the first
  // difference is, which over many attempts is enough.
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1),
  )
}

Answer 2xx once you have stored it. Anything else is retried with widening backoff over about two hours, and every attempt is visible in Settings with the status we got back.