Preview — full authorized API docs coming later

GeoIntel Core API Documentation Preview

Developer-facing overview of Place Signals endpoints, authentication model, source transparency, and planned API surfaces.

Documentation status

This page is public-safe orientation material. It is not the complete OpenAPI or Swagger reference, and preview endpoint shapes may change before external partner integration.

API surface

Endpoint families

These cards describe intended API families and access boundaries. Protected and internal endpoints must stay behind authorization until explicitly promoted.

planned / preview

Reports API

Create and retrieve business/location reports.

Example route: /api/v1/reports
Access: authenticated

planned / preview

Places API

Resolve places, geographies, and candidate markets.

Example route: /api/v1/places
Access: authenticated

planned / preview

Scores API

Retrieve score breakdowns and confidence metadata.

Example route: /api/v1/scores
Access: authenticated

partially documented

Sources API

Inspect source status, freshness, caveats, and coverage.

Example route: /api/v1/sources
Access: public-safe summary or authenticated detail

internal only

Admin / Owner API

Owner/admin governance, validation, lifecycle, and monitoring.

Example route: /api/v1/admin/*
Access: protected internal

Authentication model

Public marketing and docs-preview pages do not require sign-in.
App and report-generation routes may require sign-in before work can be saved or generated.
API docs and Swagger-style interactive docs remain protected until authorized.
Owner/admin routes must stay internal and role-gated.

Illustrative request

Illustrative preview only — endpoint shape may change.

curl -X POST https://api.placesignals.com/api/v1/reports \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "businessType": "Specialty coffee shop",
    "places": ["Bend, OR", "Boise, ID"],
    "priorities": ["growth", "cost", "talent"]
  }'

Mock response preview

Mock/preview response only — not a live production contract.

{
  "reportId": "rpt_preview_coffee_bend_boise",
  "overallScore": 82,
  "recommendation": "Promising, but margin-sensitive",
  "confidence": "medium-high",
  "sourceSummary": [
    {
      "source": "Census / ACS",
      "status": "public-source context",
      "caveat": "Estimates may lag current local conditions."
    },
    {
      "source": "BLS labor indicators",
      "status": "labor-market context",
      "caveat": "Occupational detail varies by geography."
    },
    {
      "source": "Place Signals scoring model",
      "status": "preview methodology",
      "caveat": "Endpoint shape may change before external release."
    }
  ],
  "caveats": [
    "Illustrative preview only.",
    "Use for market shortlisting, not lease-level diligence.",
    "Live source availability depends on endpoint authorization and source lifecycle status."
  ]
}

Developer readiness checklist

Endpoint inventory

needs completion

Canonical public, authenticated, and internal endpoint list still needs promotion evidence.

Auth examples

preview

Bearer-token examples are illustrative until API-key and developer-console flows are finalized.

Request/response schemas

needs completion

Representative schemas are shown as preview examples, not final contracts.

Error catalog

planned

Validation, auth, rate-limit, unavailable-source, and internal-error responses need a formal catalog.

Source/caveat metadata

partially documented

Public-safe source registry pages exist; endpoint-level metadata still needs lifecycle validation.

SDK examples

planned

TypeScript SDK packaging and examples should be verified before external publishing.

Swagger/OpenAPI UI

protected

Interactive docs remain protected until authorized and validated.

Public-safe next steps

Related docs and product previews

Use these public routes for source transparency, legal caveats, and report-preview orientation while interactive Swagger/OpenAPI docs remain protected.

View data source registryBrowsable source status, freshness, coverage, and caveats.View legal data-source notesAttribution, limits, rights, and legal caveat language.Preview sample reportPublic demo route for report structure and explanation style.Start app flowSign-in may be required before creating a report.