{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/smarterweather-com/json-schema/smarterweather-com-geocode-results-response-schema.json",
  "title": "GeocodeResultsResponse",
  "description": "Envelope returned by `GET /v1/geocode/autosuggest` and\n`GET /v1/geocode/search`. `results` is always present. `meta`\nis a stable, documented, optional field: autosuggest includes\nit only when the results are incomplete, and clients should\ntreat any `meta.warnings` entry as incomplete results.\nAdditional undocumented sibling fields may appear without a\nsw-api release (e.g. server-side annotations); ignore them.\n\nAn empty array is returned when no candidates match.\n",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/smarterweather-com-geocode-api-openapi.yml#/components/schemas/GeocodeResultsResponse",
  "type": "object",
  "required": [
    "results"
  ],
  "properties": {
    "results": {
      "type": "array",
      "description": "Match candidates, ordered by match score (best first).",
      "items": {
        "$ref": "#/$defs/GeocodeAutosuggestResult"
      }
    },
    "meta": {
      "$ref": "#/$defs/Meta",
      "description": "Autosuggest only. Present only when the results are\nincomplete; `meta.warnings[]` names each section that did\nnot finish. Absent on complete responses and on search.\n"
    }
  },
  "additionalProperties": true,
  "$defs": {
    "GeocodeAutosuggestResult": {
      "type": "object",
      "description": "Single forward-geocode candidate. Most fields are JSON `null`\nwhen the source record lacks them. `type` is the result kind\n(`place`, `zip`, `address`, `poi`).\n\nForward-compat: additional fields may appear without a\nsw-api release.\n",
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Populated-place name."
        },
        "state": {
          "type": [
            "string",
            "null"
          ],
          "description": "2-letter US state code."
        },
        "state_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Full state / region label."
        },
        "county": {
          "type": [
            "string",
            "null"
          ],
          "description": "County or equivalent admin-2 area."
        },
        "zip": {
          "type": [
            "string",
            "null"
          ],
          "description": "Representative ZIP for the place (or query ZIP for ZIP search)."
        },
        "lat": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "Centroid latitude in decimal degrees."
        },
        "lon": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "Centroid longitude in decimal degrees."
        },
        "population": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Population estimate, when known."
        },
        "timezone": {
          "type": [
            "string",
            "null"
          ],
          "description": "IANA timezone identifier covering the centroid."
        },
        "type": {
          "type": "string",
          "description": "Result kind. Emitted values are\n`place`, `zip`, `address`, `poi`. Treat as opaque --\nnew types may appear without a sw-api release.\n"
        },
        "place_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Census place GEOID. Same key as the v2 basemap tile `id`.\nPresent on place results; omitted for ZIP results.\n"
        },
        "id": {
          "type": "string",
          "description": "Stable row id for address and POI hits (and some place\nrows). Omitted when the result has no id.\n"
        },
        "title": {
          "type": "string",
          "description": "Primary two-line copy (street or POI name). Prefer over\n`name` for `address` and `poi` rows.\n"
        },
        "subtitle": {
          "type": "string",
          "description": "Secondary two-line copy (city, state).\n"
        }
      },
      "additionalProperties": true
    },
    "Meta": {
      "type": "object",
      "description": "Per-response metadata: response schema version, generation time,\nupstream data freshness, and any non-fatal warnings.\n",
      "required": [
        "schema_version",
        "generated_at"
      ],
      "properties": {
        "schema_version": {
          "type": "string",
          "description": "Response schema version, a semver string (currently `1.0.0`).\nThe major part changes only with a non-additive change, which\nfollows the deprecation policy. Cache on it if you cache\nresponse shapes.\n"
        },
        "generated_at": {
          "type": "string",
          "format": "date-time",
          "description": "Server time at which this response body was generated."
        },
        "freshness": {
          "type": "array",
          "description": "Freshness metadata for each upstream data source used. It never omits a product whose data produced a forecast row or section this response serves, and may list one whose contribution is not visible: attribution is per row, so a masked value or a field projection (`fields`, `view`) does not narrow it.",
          "items": {
            "$ref": "#/$defs/SourceFreshness"
          }
        },
        "warnings": {
          "type": "array",
          "description": "Non-fatal warnings generated during request fulfillment. Each\nentry has a stable `code` clients can branch on and a\nhuman-readable `detail`.\n",
          "items": {
            "$ref": "#/$defs/MetaWarning"
          }
        },
        "hourly_sampling": {
          "type": "object",
          "description": "Present only when `hourly_step` dropped at least one hourly\nrow. Echoes the effective thinning so a thinned series is\ndistinguishable from a short forecast: every row is kept below\n`from_hour` hours from `hourly[0].time`, then one row every\n`step_hours` hours.\n",
          "required": [
            "step_hours",
            "from_hour"
          ],
          "properties": {
            "step_hours": {
              "type": "integer",
              "minimum": 2,
              "maximum": 24,
              "description": "Effective `hourly_step`."
            },
            "from_hour": {
              "type": "integer",
              "minimum": 0,
              "maximum": 168,
              "description": "Effective `hourly_step_from`."
            }
          }
        }
      }
    },
    "MetaWarning": {
      "type": "object",
      "required": [
        "code",
        "section"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-parseable warning code. Clients should branch on\n`code`, not on `detail`.\n\n- `partial_fetch`: the section could not be fully fetched and is\n  missing or incomplete.\n- `upstream_timeout`: an upstream weather source timed out, so\n  the section is missing or incomplete.\n- `upstream_unavailable`: an upstream weather source was\n  unreachable, or (for a section not enabled for every key,\n  such as `sky`) access could not be checked, so the section\n  is missing or incomplete; retry later.\n- `coverage_limited`: the data does not cover this location\n  (for example no nearby station, or a product outside its\n  domain); retrying will not help.\n- `geocode_ambiguous`: the place name matched more than one\n  location; the response uses the best match.\n- `stale_response`: the section was served from a recent cached\n  copy because the upstream source failed.\n- `stale_source`: one upstream product's latest data is older\n  than its source's freshness limit. `product_id` names the\n  product (its age is the `meta.freshness` entry with the same\n  `product_id`) and `fields` lists the fields in `section` it\n  leaves `null` (or omits, for optional fields such as\n  `aqi_category`). Unlike `stale_response`, the response was not\n  replayed from cache.\n- `not_enabled`: the requested section is not enabled for this\n  API key.\n\nNew codes may be added without a breaking-change announcement;\ntreat an unknown code as informational.\n",
          "enum": [
            "partial_fetch",
            "upstream_timeout",
            "upstream_unavailable",
            "coverage_limited",
            "geocode_ambiguous",
            "stale_response",
            "stale_source",
            "not_enabled"
          ]
        },
        "section": {
          "type": "string",
          "description": "Response section the warning applies to (e.g., `\"alerts\"`,\n`\"hourly\"`, `\"outlooks\"`). May also be `\"_request\"` for\nrequest-level warnings.\n"
        },
        "detail": {
          "type": "string",
          "description": "Human-readable explanation."
        },
        "product_id": {
          "type": "string",
          "description": "Catalog product id (`GET /v1/catalog/{product_id}`) of the\nupstream product the warning is about; the same id as the\nproduct's `meta.freshness` entry. Set only for `stale_source`.\n"
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Response fields in `section` that this warning leaves `null` or\nomits. Set only for `stale_source`.\n"
        }
      }
    },
    "SourceFreshness": {
      "type": "object",
      "description": "Freshness metadata for a single upstream data source that supplied data to a forecast row or section in this response.",
      "required": [
        "source",
        "product_id",
        "age_seconds"
      ],
      "properties": {
        "source": {
          "type": "string",
          "description": "Source family (e.g., `rtma`, `hrrr`, `nbm`, `mrms`)."
        },
        "product_id": {
          "type": "string",
          "description": "Specific product identifier."
        },
        "reference_time": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Model run / observation reference time."
        },
        "latest_valid": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Latest valid time represented in the source."
        },
        "age_seconds": {
          "type": "integer",
          "minimum": 0,
          "description": "Seconds elapsed since `reference_time`, or since `latest_valid`\nwhen there is no `reference_time` (an observed product with no\nrun). An observed daily product (for example\n`rtma_daily_ag_temps_*`) stamps each day at its start, so its age\ncounts from the start of its latest observed day, not from its\nlast update.\n"
        }
      }
    }
  }
}