TypeScript SDK

    Typed client surface for canonical Homecastr data contracts

    Homecastr now has a typed TypeScript client for geography forecasts, the benchmark namespace, and the published/api/v1/data/* discovery resources. The contract goal is simple: one vocabulary for REST, MCP, OpenAPI, docs, and SDKs, even when an asset stays metadata-only or restricted.

    Release package

    The versioned @homecastr/sdk package has named helpers for the published OpenAPI operations, including discovery, forecasts, artifacts, status, usage, and API key creation.

    Canonical source of truth

    The stable wire contract remains the OpenAPI spec plus the hc.*.v1 schema bundle. TypeScript helpers should mirror those contracts, not rename fields or invent alternate payloads.

    Packaging status

    The TypeScript and Python packages build and test in this repository. Registry publication is a separate release action, so the docs do not claim that either registry already serves them.

    Surface map

    Forecast outputs

    • client.forecasts.tract()
    • client.forecasts.county()
    • client.forecasts.state()

    Standardized data

    • client.entities.get()
    • client.geographies.getCrosswalk()
    • client.panels.lineage()
    • client.schemas.list() / get()

    Evaluation

    • client.vintages.get()
    • client.benchmarks.get()
    • client.benchmarks.catalog()
    • client.benchmarks.vintages()
    • client.benchmarks.backtests()
    • client.benchmarks.sources()

    Discovery and trust

    • client.dataAssets.list() / get()
    • client.sources.list() / get()
    • client.panels.lineage()
    • client.coverage.get()
    • client.coverage.sources()
    • client.coverage.map()
    • client.acquisition.publicRecords()
    • client.schemas.list() / get()
    • client.provenance.get()
    • client.artifacts.get() / download()

    Interactive scenes

    • client.scenes.brickell()
    • client.scenes.brickellContext()
    • client.scenes.brickellScenario()
    • client.scenes.pickBrickellScenario()

    Standardization rules

    Keep raw

    Immutable snapshots and terms evidence stay distinct from public query records. The SDK should expose metadata and artifact links without pretending raw payloads are universally redistributable.

    Normalize once

    Observation, panel, forecast, and benchmark records should share canonical entity, time, metric, provenance, and access fields so downstream repos can switch models without rewriting ingestion logic.

    Package last

    Published npm packaging should follow the OpenAPI and schema contracts. Ergonomic helpers are welcome, but they should wrap the canonical fields rather than create a second vocabulary.

    Current example

    import { createHomecastrClient } from "@homecastr/sdk"

const client = createHomecastrClient({
  apiKey: process.env.HOMECASTR_API_KEY,
})

const assets = await client.dataAssets.list({
  dataFamily: "forecast_output",
  publicStatus: "launch",
})

const source = await client.sources.get("source.hcad_houston.assessor")
const lineage = await client.panels.lineage("panel.acs_nationwide")

const forecast = await client.forecasts.tract("48201231400")
const scene = await client.scenes.brickell()

const benchmarkCatalog = await client.benchmarks.catalog({
  phase: "phase_1",
})

    The release package lives at packages/sdk-typescript. It preserves server field names and exposes retry metadata when the API returns a temporary data-availability error.

    Python SDK

    The release package lives at packages/sdk-python and is configured for the homecastr package name. Publish it before presenting a PyPI install command as live. It defaults to Homecastr and accepts base_url="https://worldcastr.com" for Worldcastr.

    Release checks

    Run both package test suites, publish from a reviewed release commit, and verify registry metadata before adding live install commands.

    Keep method names aligned with REST and MCP so downstream adapters for Chronos, TimesFM, Nixtla, Prior Labs, and similar consumers can share one canonical ingestion contract.

    Preserve provenance and access metadata in every helper so benchmark-only, consumer-feed, and training-eligible assets remain distinguishable after conversion.

    REST reference MCP docsSchema reference

    Documentation

    Start with the job you need to do, then move into the complete interface reference.

    Start and build

    Choose a task before choosing a protocol.

    Start HereForecastsData CatalogBenchmarks

    Interfaces

    REST, MCP, and typed client references.

    REST QuickstartFull API ReferenceMCP ToolsTypeScript SDKPython SDK

    Trust and operations

    Contracts, methodology, and live health.

    Schema ReferenceStatusMethodology