GeocodeResultsResponse
Envelope returned by `GET /v1/geocode/autosuggest` and `GET /v1/geocode/search`. `results` is always present. `meta` is a stable, documented, optional field: autosuggest includes it only when the results are incomplete, and clients should treat any `meta.warnings` entry as incomplete results. Additional undocumented sibling fields may appear without a sw-api release (e.g. server-side annotations); ignore them. An empty array is returned when no candidates match.
Properties
| Name | Type | Description |
|---|---|---|
| results | array | Match candidates, ordered by match score (best first). |
| meta | object | Autosuggest only. Present only when the results are incomplete; `meta.warnings[]` names each section that did not finish. Absent on complete responses and on search. |
JSON Schema
{
"$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"
}
}
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
curl "https://apis.io/api/v1/json-schemas/smarterweather-com-geocode-results-response"
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.