{ "openapi": "3.1.0", "info": { "title": "Korzy API", "version": "1.0.0", "summary": "United States land, infrastructure, energy, environmental and logistics records as JSON.", "description": "The Korzy API returns structured land, infrastructure, energy, environmental and logistics records for the United States as JSON over HTTPS: lookups at an address or point, batch enrichment, records by ID, cited answers to questions, support requests and a free field catalog.\n\nSend `Authorization: Bearer `. Create API keys on your account page (https://app.korzy.co/account); an OAuth access token from Korzy sign-in also works. Every route needs the `api:read` scope. POST bodies are JSON objects of at most 64 KB.\n\nEvery successful JSON response includes `request_id` and `credits` (`charged`, `refunded`); the exception is `POST /v1/ask` and its stream's `done` event, whose `credits` is an integer. Errors return a `detail` message and, where applicable, a machine-readable `code`. Error responses are refunded in full; failed enrich items and lookup sections are refunded individually. Owner fields are returned only by `POST /v1/enrich` with the owner group.\n\nEach operation's `x-korzy-credits` gives its cost: `min` and `max` over valid requests, plus the per-section (`sections`) or per-item (`per_item`, `owner_multiplier`) terms where the cost depends on the body.\n\nCredits:\n\n- A location lookup (address or coordinates) with its parcels: 1 credit\n- Each lookup section: utilities, environment, logistics, data centers, power, grid, parcel boundaries: +1 credit\n- Each lookup section: terrain: +2 credits\n- Each address, point or parcel ID in an enrich batch (up to 25 per request): 1 credit\n- Each enrich item with owner fields (available on request, opt-in per organization): 2 credits\n- A record by ID: a parcel, power plant, data center, utility or other record: 1 credit\n- A question answered by Ask, with cited sources: 10 credits\n- Support requests and the field catalog: Free", "termsOfService": "https://korzy.co/terms/", "contact": { "name": "Korzy", "url": "https://korzy.co/contact/" } }, "externalDocs": { "description": "Korzy API docs", "url": "https://korzy.co/docs/" }, "servers": [ { "url": "https://api.korzy.co" } ], "security": [ { "bearer": [ "api:read" ] } ], "tags": [ { "name": "Lookup", "description": "Everything Korzy knows about one location: the parcels there, and any of the sections you ask for. 1 credit for the parcels, plus each section's credits." }, { "name": "Enrich", "description": "Selected parcel fields for a batch of up to 25 addresses, points or parcel IDs. 1 credit per item, 2 credits per item with owner fields. Owner fields are available only here." }, { "name": "Records", "description": "One record by the `id` a lookup or enrich returned: a parcel, power plant, data-center project, utility, energy facility, grid-capacity, property or nearby record." }, { "name": "Ask", "description": "A question about one place, answered from Korzy data with cited sources. The answer looks up parcels, sections and records itself; owner fields are never used. The question and the Korzy data it draws on are sent to an external language model that writes the answer. 10 credits per question, at most 6 a minute and 200 a day per organization." }, { "name": "Support", "description": "Report missing or wrong data, request a feature or report a bug. Free; at most 10 an hour and 30 a day per organization." }, { "name": "Fields", "description": "What each route returns and costs, read by programs and agents before they spend credits. Free." } ], "paths": { "/v1/lookup": { "post": { "operationId": "postLookup", "tags": [ "Lookup" ], "summary": "The parcels at an address or point, and the sections you ask for", "description": "The parcels at an address or point, and the sections you ask for: utilities, environment, logistics, data centers, power, grid, terrain and parcel boundaries.\n\nSend exactly one location: `address`, or `longitude` and `latitude`. An address must match exactly; otherwise the request returns 404 `address_not_found` and is refunded.\n\nA section that fails or is unavailable has `status` `error` or `unavailable` and its credits are refunded; the rest of the response is unaffected.\n\nCost: 1 credit, plus 1–2 credits per section (up to 10 credits).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupInput" }, "examples": { "lookup_address": { "summary": "An address with utilities and environment", "value": { "address": "714 Mordecai Towne Pl, Raleigh, NC", "sections": [ "utilities", "environment" ] } }, "lookup_point": { "summary": "A point with data centers, power and grid", "value": { "longitude": -77.4874, "latitude": 39.0438, "sections": [ "datacenters", "power", "grid" ] } } } } }, "required": true, "description": "- `address`: A street address, 3–160 characters, such as `714 Mordecai Towne Pl, Raleigh, NC`. Must match exactly; including the state gives the most precise match.\n- `longitude`: Longitude, −180 to 180. Send with `latitude` instead of `address`.\n- `latitude`: Latitude, −85 to 85.\n- `sections`: Any of `utilities`, `environment`, `logistics`, `datacenters`, `power`, `grid`, `terrain`, `boundary`. Default: none, parcels only." }, "responses": { "200": { "description": "The parcels at an address or point, and the sections you ask for", "content": { "application/json": { "schema": { "type": "object", "required": [ "location", "parcels", "sections", "credits", "request_id" ], "properties": { "location": { "type": "object", "description": "`longitude`, `latitude`, the matched `address` and `match_type` (`exact`), or nulls for a point." }, "parcels": { "type": "object", "description": "`records`: up to 20 parcels covering the point, each with `id` and the parcel fields below (never owner fields); `truncated`; `provenance` with `as_of`." }, "sections": { "type": "object", "description": "One entry per requested section: `status` (`ok`, `unavailable` or `error`), `data`, `error` and `provenance` (dataset and `as_of` date). Records carry an `id` you can pass to `/v1/records/{id}`." }, "credits": { "type": "object", "description": "`charged` and `refunded`: what this request spent and what was given back (failed items or sections)." }, "request_id": { "type": "string", "description": "ID of this request. Include it in support requests." } } }, "examples": { "lookup_address": { "summary": "An address with utilities and environment (abbreviated)", "value": { "location": { "longitude": -78.62700116632315, "latitude": 35.79988145, "address": "714 MORDECAI TOWNE PL, RALEIGH", "match_type": "exact" }, "parcels": { "records": [ { "id": "37183-676db8ae68362b7a3685", "bldgsqft": 2393, "countyname": "Wake", "latitude": 35.79988145, "longitude": -78.62700116632315, "korzy_id": "37183-676db8ae68362b7a3685", "parceladdr": "714 MORDECAI TOWNE PL", "parcelcity": "RALEIGH", "parcelid": "1714066205", "saleamt": 740000, "saledate": "2025-07-10", "statefp": "37", "taxacres": 0.03, "totalvalue": 662832, "updated": "2026-05-17", "usedesc": "R", "yearbuilt": 2009, "situs_state": null, "situs_zip": "27604", "municipality": null, "subdivision": null, "legal_description": "LO4 MORDECAI TOWNS AT COURTLAND DRIVE BM2007 -01069", "land_use_code": "RHS", "zoning_code": null, "zoning_description": null, "alternate_parcel_number": "0364254", "living_area_sqft": null, "building_count": 1, "tax_year": null, "land_value_usd": 135000, "improvement_value_usd": 527832, "assessed_value_usd": null, "market_value_usd": null, "taxable_value_usd": null, "tax_amount_usd": null, "last_sale_document": "Deed Book/Page 019954/02049", "geoid": "37183", "parcelid2": "0364254", "ogparcelid": "1714066205", "taxacctnum": null } ], "truncated": false, "provenance": { "source": "Korzy parcels", "as_of": "2026-11-04" } }, "sections": { "utilities": { "status": "ok", "data": { "water": [ { "id": "utility:water:29943", "feature_id": "water:29943", "name": "RALEIGH, CITY OF", "boundary_basis": "System Sourced" } ], "sewer": [ { "id": "utility:sewer:2161", "feature_id": "sewer:2161", "name": "NEUSE RIVER RESOURCE RECOVERY FACILITY", "boundary_basis": "Sourced" } ], "treatment_plants": [ { "id": "utility:treatment:7989", "feature_id": "treatment:7989", "name": "NORTH CARY WWTP", "distance_km": 14.090844006673105 }, { "id": "utility:treatment:15459", "feature_id": "treatment:15459", "name": "Smith Creek Resource Recovery Facility", "distance_km": 14.651385662091693 }, { "id": "utility:treatment:7987", "feature_id": "treatment:7987", "name": "NEUSE RIVER RESOURCE RECOVERY FACILITY", "distance_km": 15.556300140909235 } ], "truncated": { "water": false, "sewer": false } }, "error": null, "provenance": [ { "dataset": "water", "as_of": null, "data_version": "63b7c1c3-9661-4fed-a59f-ddbfff80c2e4" }, { "dataset": "sewer", "as_of": null, "data_version": "63b7c1c3-9661-4fed-a59f-ddbfff80c2e4" }, { "dataset": "treatment", "as_of": null, "data_version": "63b7c1c3-9661-4fed-a59f-ddbfff80c2e4" } ] }, "environment": { "status": "ok", "data": { "radius_km": 10, "matches": { "air_quality_areas": [ { "id": "poi:air-quality-areas:air_quality_areas:0:103", "feature_id": "air_quality_areas:0:103", "name": "Raleigh-Durham-Chapel Hill Area · Ozone 8-hr (1997 standard) · NC", "operator": null, "status": "Maintenance", "state": "NC", "city": null, "category": "Ozone 8-hr (1997 standard)", "boundary_basis": null, "source_date": null, "poi_slug": "air-quality-areas", "geometry_kind": "area" }, { "id": "poi:air-quality-areas:air_quality_areas:10:64", "feature_id": "air_quality_areas:10:64", "name": "Raleigh-Durham Area · Ozone 1-hr (1979 standard-revoked) · NC", "operator": null, "status": "Maintenance (NAAQS revoked)", "state": "NC", "city": null, "category": "Ozone 1-hr (1979 standard-revoked)", "boundary_basis": null, "source_date": null, "poi_slug": "air-quality-areas", "geometry_kind": "area" }, { "id": "poi:air-quality-areas:air_quality_areas:9:38", "feature_id": "air_quality_areas:9:38", "name": "Raleigh-Durham Area · CO (1971 Standard) · NC", "operator": null, "status": "Maintenance", "state": "NC", "city": null, "category": "CO (1971 Standard)", "boundary_basis": null, "source_date": null, "poi_slug": "air-quality-areas", "geometry_kind": "area" } ] }, "nearby": { "superfund_npl": [ { "id": "poi:superfund-npl-sites:superfund_npl:records:266", "feature_id": "superfund_npl:records:266", "name": "North Carolina State University (Lot 86, Farm Unit #1)", "operator": null, "status": "NPL Site", "state": "North Carolina", "city": "Raleigh", "category": "Superfund NPL sites", "boundary_basis": null, "source_date": null, "distance_km": 7.811814554041426, "poi_slug": "superfund-npl-sites", "geometry_kind": "point" } ], "brownfields": [ { "id": "poi:brownfields:brownfields:records:11457", "feature_id": "brownfields:records:11457", "name": "PROPERTY 25", "operator": null, "status": null, "state": "NC", "city": "RALEIGH", "category": "Brownfields", "boundary_basis": null, "source_date": null, "distance_km": 2.1660816702315127, "poi_slug": "brownfields", "geometry_kind": "point" }, { "id": "poi:brownfields:brownfields:records:4939", "feature_id": "brownfields:records:4939", "name": "702 706 E MARTIN STREET", "operator": null, "status": null, "state": "NC", "city": "RALEIGH", "category": "Brownfields", "boundary_basis": null, "source_date": null, "distance_km": 2.5975875078144046, "poi_slug": "brownfields", "geometry_kind": "point" }, { "id": "poi:brownfields:brownfields:records:3287", "feature_id": "brownfields:records:3287", "name": "301 HILLSBOROUGH STREET", "operator": null, "status": null, "state": "NC", "city": "RALEIGH", "category": "Brownfields", "boundary_basis": null, "source_date": null, "distance_km": 2.621628914901275, "poi_slug": "brownfields", "geometry_kind": "point" } ] }, "coverage": { "flood_hazard": { "status": "unavailable", "states": [], "stale_states": [], "note": "No published state package covers the reference point; coverage is unknown." }, "wetlands": { "status": "unavailable", "states": [], "stale_states": [], "note": "No published state package covers the reference point; coverage is unknown." } }, "truncated": { "brownfields": true }, "note": "Screening at the supplied reference point, not a full parcel overlap analysis. Area and line matches intersect the published geometry at that point. Nearby cleanup records use reported point locations and straight-line distance. Source coverage and geometry limitations apply; absence of a match is not an environmental clearance. Flood hazard and wetland coverage at the point is reported under coverage: no intersecting polygon is unknown, never a finding that the point is outside a flood zone or wetland." }, "error": null, "provenance": [ { "dataset": "superfund_sites", "as_of": "2026-11-05", "data_version": "20261105T023448534475Z" }, { "dataset": "superfund_npl", "as_of": "2026-11-05", "data_version": "20261105T023448534475Z" }, { "dataset": "brownfields", "as_of": "2026-11-05", "data_version": "20261105T023448534475Z" } ] } }, "credits": { "charged": 3, "refunded": 0 }, "credits_url": "/v1/fields#attribution", "request_id": "5479539e-2cd0-4d09-91df-5dbef1fd5676" } }, "lookup_point": { "summary": "A point with data centers, power and grid (abbreviated)", "value": { "location": { "longitude": -77.4874, "latitude": 39.0438, "address": null, "match_type": null }, "parcels": { "records": [ { "id": "51107-19850a84f297b5dd3844", "bldgsqft": null, "countyname": "Loudoun", "latitude": 39.043759, "longitude": -77.48727612877775, "korzy_id": "51107-19850a84f297b5dd3844", "parceladdr": "20702 ASHBURN RD", "parcelcity": "Loudoun County", "parcelid": "085165792000", "saleamt": null, "saledate": null, "statefp": "51", "taxacres": 0.37, "totalvalue": null, "updated": "2026-07-31", "usedesc": null, "yearbuilt": null, "situs_state": null, "situs_zip": "20147", "municipality": "Loudoun County", "subdivision": null, "legal_description": null, "land_use_code": null, "zoning_code": null, "zoning_description": null, "alternate_parcel_number": "085165792000", "living_area_sqft": null, "building_count": null, "tax_year": null, "land_value_usd": null, "improvement_value_usd": null, "assessed_value_usd": null, "market_value_usd": null, "taxable_value_usd": null, "tax_amount_usd": null, "last_sale_document": null, "geoid": "51107", "parcelid2": "5110700044723", "ogparcelid": "085165792000", "taxacctnum": "085165792000" } ], "truncated": false, "provenance": { "source": "Korzy parcels", "as_of": "2026-11-04" } }, "sections": { "datacenters": { "status": "ok", "data": { "radius_km": 10, "projects": [ { "id": "datacenter:dc_1aac762b0a7956be5cdb", "project_id": "dc_1aac762b0a7956be5cdb", "name": "Equinix Ashburn Campus (DC1–DC15)", "operator": "Equinix", "status": "operating", "state": "VA", "city": "Ashburn", "address": "", "longitude": -77.4875, "latitude": 39.0437, "location_precision": "exact", "operational_mw": 500, "planned_mw": null, "it_mw": null, "source_count": 1, "source_date": "2026-09-14", "mapped": true, "distance_km": 0.014079285656724639 }, { "id": "datacenter:dc_8538a6a80d32ecb8753b", "project_id": "dc_8538a6a80d32ecb8753b", "name": "STACK NVA Loudoun 144MW Hyperscale Campus", "operator": "STACK Infrastructure", "status": "permitted", "state": "VA", "city": "Ashburn", "address": "", "longitude": -77.49, "latitude": 39.04, "location_precision": "exact", "operational_mw": null, "planned_mw": 144, "it_mw": null, "source_count": 1, "source_date": "2026-09-21", "mapped": true, "distance_km": 0.4784995143588063 }, { "id": "datacenter:dc_fbe24f4974aa4e1c69aa", "project_id": "dc_fbe24f4974aa4e1c69aa", "name": "Bridgefield Tech Center", "operator": "Amazon Web Services", "status": "proposed", "state": "VA", "city": "Ashburn", "address": "", "longitude": -77.4744148, "latitude": 39.029784, "location_precision": "approximate", "operational_mw": null, "planned_mw": null, "it_mw": null, "source_count": 1, "source_date": "2026-08-26", "mapped": true, "distance_km": 1.9200998223812187 } ], "truncated": true, "note": "Straight-line distance to the reported project point; inspect location_precision. Projects merge supported source matches, not every nearby building. Approximate locations do not identify a parcel. Reported IT load, facility power, planned capacity and estimates remain separate source claims. No record or unknown status does not establish absence or inactivity." }, "error": null, "provenance": [ { "dataset": "datacenters", "as_of": "2026-11-02", "data_version": "20261102T123021962884Z" } ] }, "power": { "status": "ok", "data": { "radius_km": 50, "plants": [ { "id": "plant:59004", "plant_id": "59004", "plant_name": "Potomac Energy Center, LLC", "state": "VA", "longitude": -77.545, "latitude": 39.058056, "site_status": "operating", "primary_fuel": "gas", "nameplate_mw": 812, "proposed_nameplate_mw": null, "generator_count": 3, "distance_km": 5.22 }, { "id": "plant:70232", "plant_id": "70232", "plant_name": "Evergreen Energy Center, LLC", "state": "VA", "longitude": -77.581908, "latitude": 39.044885, "site_status": "proposed", "primary_fuel": "storage", "nameplate_mw": null, "proposed_nameplate_mw": 20, "generator_count": 1, "distance_km": 8.163 }, { "id": "plant:65043", "plant_id": "65043", "plant_name": "Dulles Solar and Storage", "state": "VA", "longitude": -77.5, "latitude": 38.95, "site_status": "proposed", "primary_fuel": "solar", "nameplate_mw": null, "proposed_nameplate_mw": 150, "generator_count": 2, "distance_km": 10.487 } ], "truncated": true, "report_year": 2025, "note": "Nameplate MW is generation inventory, not available power or interconnection capacity. Distances are straight-line." }, "error": null, "provenance": [ { "dataset": "power_plants", "as_of": null, "data_version": "2b27929d26cc1da9ad6a530da1cac6718cd8496098ee560c4d47cfffd96d08ba" } ] }, "grid": { "status": "ok", "data": { "radius_km": 10, "capacity": [ { "source_object_id": "15787", "utility": "phi", "data_kind": "load_headroom", "scope": "feeder", "season": "unspecified", "phase": "1,2", "scenario": "published", "coverage": "DC, Maryland, Delaware, New Jersey", "feeder_id": "15230", "substation": "QUINCE ORCHARD SUB. 118", "substation_id": null, "transformer_id": null, "state": null, "bank_id": null, "voltage_kv": 13.8, "source_date": "2026-02-16T15:41:05+00:00", "source_band": null, "local_headroom_mw": 3, "local_headroom_mva": null, "feeder_headroom_mw": 3, "feeder_headroom_mva": null, "substation_headroom_mw": 40.52, "substation_headroom_mva": null, "bank_headroom_mw": null, "bank_headroom_mva": null, "qualifications": null, "asset_status": null, "asset_type": null, "address": null, "project_name": null, "project_type": null, "project_status": null, "expected_in_service": null, "project_description": null, "transmission_node_id": null, "backfeed_protection": null, "fetched_at": "2026-11-01T11:03:11.689514+00:00", "geometry_repaired": false, "observations": [ { "metric": "headroom", "scenario": "published", "scope": "local", "season": "unspecified", "source_field": "Capacity_MW", "unit": "MW", "value": 3, "year": null }, { "metric": "headroom", "scenario": "published", "scope": "feeder", "season": "unspecified", "source_field": "Feeder_Capacity_MW", "unit": "MW", "value": 3, "year": null }, { "metric": "headroom", "scenario": "published", "scope": "substation", "season": "unspecified", "source_field": "Substation_Capacity_MW", "unit": "MW", "value": 40.52, "year": null } ] }, { "source_object_id": "15792", "utility": "phi", "data_kind": "load_headroom", "scope": "feeder", "season": "unspecified", "phase": "1,2", "scenario": "published", "coverage": "DC, Maryland, Delaware, New Jersey", "feeder_id": "15235", "substation": "QUINCE ORCHARD SUB. 118", "substation_id": null, "transformer_id": null, "state": null, "bank_id": null, "voltage_kv": 13.8, "source_date": "2026-02-16T15:41:05+00:00", "source_band": null, "local_headroom_mw": 6.02, "local_headroom_mva": null, "feeder_headroom_mw": 6.02, "feeder_headroom_mva": null, "substation_headroom_mw": 40.52, "substation_headroom_mva": null, "bank_headroom_mw": null, "bank_headroom_mva": null, "qualifications": null, "asset_status": null, "asset_type": null, "address": null, "project_name": null, "project_type": null, "project_status": null, "expected_in_service": null, "project_description": null, "transmission_node_id": null, "backfeed_protection": null, "fetched_at": "2026-11-01T11:03:11.689514+00:00", "geometry_repaired": false, "observations": [ { "metric": "headroom", "scenario": "published", "scope": "local", "season": "unspecified", "source_field": "Capacity_MW", "unit": "MW", "value": 6.02, "year": null }, { "metric": "headroom", "scenario": "published", "scope": "feeder", "season": "unspecified", "source_field": "Feeder_Capacity_MW", "unit": "MW", "value": 6.02, "year": null }, { "metric": "headroom", "scenario": "published", "scope": "substation", "season": "unspecified", "source_field": "Substation_Capacity_MW", "unit": "MW", "value": 40.52, "year": null } ] }, { "source_object_id": "18092", "utility": "phi", "data_kind": "load_headroom", "scope": "feeder", "season": "unspecified", "phase": "3", "scenario": "published", "coverage": "DC, Maryland, Delaware, New Jersey", "feeder_id": "15230", "substation": "QUINCE ORCHARD SUB. 118", "substation_id": null, "transformer_id": null, "state": null, "bank_id": null, "voltage_kv": 13.8, "source_date": "2026-02-16T17:18:32+00:00", "source_band": null, "local_headroom_mw": 3, "local_headroom_mva": null, "feeder_headroom_mw": 3, "feeder_headroom_mva": null, "substation_headroom_mw": 40.52, "substation_headroom_mva": null, "bank_headroom_mw": null, "bank_headroom_mva": null, "qualifications": null, "asset_status": null, "asset_type": null, "address": null, "project_name": null, "project_type": null, "project_status": null, "expected_in_service": null, "project_description": null, "transmission_node_id": null, "backfeed_protection": null, "fetched_at": "2026-11-01T11:01:32.304797+00:00", "geometry_repaired": false, "observations": [ { "metric": "headroom", "scenario": "published", "scope": "local", "season": "unspecified", "source_field": "Capacity_MW", "unit": "MW", "value": 3, "year": null }, { "metric": "headroom", "scenario": "published", "scope": "feeder", "season": "unspecified", "source_field": "Feeder_Capacity_MW", "unit": "MW", "value": 3, "year": null }, { "metric": "headroom", "scenario": "published", "scope": "substation", "season": "unspecified", "source_field": "Substation_Capacity_MW", "unit": "MW", "value": 40.52, "year": null } ] } ], "truncated": false, "transmission": { "radius_km": 5, "lines": [ { "id": "poi:transmission-lines:142003", "line_id": "142003", "status": "IN SERVICE", "owner": "VIRGINIA ELECTRIC & POWER CO", "voltage_kv": 230, "voltage_class": "220-287", "line_type": "AC; OVERHEAD", "substation_1": "ASHBURN", "substation_2": "BEAUMEADE", "source_date": "2014-06-17T00:00:00+00:00", "distance_km": 0.02 }, { "id": "poi:transmission-lines:119843", "line_id": "119843", "status": "IN SERVICE", "owner": "VIRGINIA ELECTRIC & POWER CO", "voltage_kv": 230, "voltage_class": "220-287", "line_type": "AC; OVERHEAD", "substation_1": "ASHBURN", "substation_2": "BEAUMEADE", "source_date": "2014-09-03T00:00:00+00:00", "distance_km": 0.023 }, { "id": "poi:transmission-lines:115875", "line_id": "115875", "status": "IN SERVICE", "owner": "VIRGINIA ELECTRIC & POWER CO", "voltage_kv": 230, "voltage_class": "220-287", "line_type": "AC; OVERHEAD", "substation_1": "PLEASANT VIEW", "substation_2": "ASHBURN", "source_date": "2014-09-03T00:00:00+00:00", "distance_km": 1.267 } ], "truncated": true }, "note": "Utility screening estimates, not reserved power or confirmed parcel service. Shared feeder, bank and substation values repeat across source geometries and must not be summed. MW and MVA are separate; forecasts, ratings and available load headroom are separate observations. Missing values are unknown." }, "error": null, "provenance": [ { "dataset": "grid_capacity", "as_of": "2026-11-01", "data_version": "20261101T110021240424Z-ae344efa" }, { "dataset": "transmission", "as_of": "2026-11-03", "data_version": null } ] } }, "credits": { "charged": 4, "refunded": 0 }, "credits_url": "/v1/fields#attribution", "request_id": "f78daf11-f76a-4790-abaf-26cc35d85778" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "description": "- `address_not_found`: No exact match for the address. Refunded.\n- `use_v1`: Unknown route. Paths under `/api` are not part of the public API; use `/v1`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "description": "- `invalid_request`: The body is missing a field, has an unknown one or a value out of range. `detail` says which.\n- `invalid_json`: A POST body is not a JSON object. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-korzy-credits": { "min": 1, "max": 10, "base": 1, "sections": { "utilities": 1, "environment": 1, "logistics": 1, "datacenters": 1, "power": 1, "grid": 1, "terrain": 2, "boundary": 1 } } } }, "/v1/enrich": { "post": { "operationId": "postEnrich", "tags": [ "Enrich" ], "summary": "Parcel fields for up to 25 items in one request", "description": "Parcel fields for up to 25 items in one request. Each item is an address, a point or a `korzy_id`.\n\nAsking for the `owner` group or any of its fields, or a preset that includes it, makes every item cost 2 credits. Lookup, records and Ask never return owner fields.\n\nA valid request always returns 200. Items that fail have `status` `error` and their credits are refunded.\n\nCost: 1 credit per item; 2 credits per item with owner fields.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichInput" }, "examples": { "enrich_basic": { "summary": "Three kinds of item with the basic preset", "value": { "items": [ { "address": "714 Mordecai Towne Pl, Raleigh, NC" }, { "korzy_id": "37183-676db8ae68362b7a3685" }, { "longitude": -78.627, "latitude": 35.7999 } ], "preset": "basic" } }, "enrich_owner": { "summary": "Owner and sale fields", "value": { "items": [ { "address": "1600 Glenarm Pl, Denver, CO" } ], "fields": [ "identity", "sale", "owner" ] } } } } }, "required": true, "description": "- `items` (required): 1–25 items, each `{\"address\": …}`, `{\"longitude\": …, \"latitude\": …}` or `{\"korzy_id\": …}`.\n- `fields`: Field names or groups (`identity`, `address`, `location`, `land`, `building`, `value`, `sale`, `owner`); see [Enrich fields](https://korzy.co/docs/reference/#enrich-fields). Not with `preset`.\n- `preset`: `basic`, `standard`, `owner`. Default `standard` when neither `fields` nor `preset` is sent." }, "responses": { "200": { "description": "Parcel fields for up to 25 items in one request", "content": { "application/json": { "schema": { "type": "object", "required": [ "fields", "results", "credits", "request_id" ], "properties": { "fields": { "type": "array", "description": "The field names returned, after groups and presets are expanded." }, "results": { "type": "array", "description": "One entry per item, in order: `index`, `input`, `status` (`ok` or `error`), `records` (up to 20, each with `id`, `korzy_id` and the selected fields), `truncated` and `credits`; or `error` with `code` (`not_found`, `invalid` or `unavailable`) and `detail`." }, "credits": { "type": "object", "description": "`charged` and `refunded`: what this request spent and what was given back (failed items or sections)." }, "request_id": { "type": "string", "description": "ID of this request. Include it in support requests." } } }, "examples": { "enrich_basic": { "summary": "Three kinds of item with the basic preset (abbreviated)", "value": { "fields": [ "korzy_id", "parcelid", "alternate_parcel_number" ], "results": [ { "index": 0, "input": { "address": "714 Mordecai Towne Pl, Raleigh, NC" }, "status": "ok", "records": [ { "id": "37183-676db8ae68362b7a3685", "korzy_id": "37183-676db8ae68362b7a3685", "parcelid": "1714066205", "alternate_parcel_number": "0364254", "statefp": "37", "geoid": "37183", "countyname": "Wake", "updated": "2026-05-17", "parceladdr": "714 MORDECAI TOWNE PL", "parcelcity": "RALEIGH", "situs_state": null, "situs_zip": "27604", "municipality": null, "subdivision": null, "legal_description": "LO4 MORDECAI TOWNS AT COURTLAND DRIVE BM2007 -01069", "longitude": -78.62700116632315, "latitude": 35.79988145, "taxacres": 0.03, "land_use_code": "RHS", "usedesc": "R", "zoning_code": null, "zoning_description": null } ], "truncated": false, "credits": 1 }, { "index": 1, "input": { "korzy_id": "37183-676db8ae68362b7a3685" }, "status": "ok", "records": [ { "id": "37183-676db8ae68362b7a3685", "korzy_id": "37183-676db8ae68362b7a3685", "parcelid": "1714066205", "alternate_parcel_number": "0364254", "statefp": "37", "geoid": "37183", "countyname": "Wake", "updated": "2026-05-17", "parceladdr": "714 MORDECAI TOWNE PL", "parcelcity": "RALEIGH", "situs_state": null, "situs_zip": "27604", "municipality": null, "subdivision": null, "legal_description": "LO4 MORDECAI TOWNS AT COURTLAND DRIVE BM2007 -01069", "longitude": -78.62700116632315, "latitude": 35.79988145, "taxacres": 0.03, "land_use_code": "RHS", "usedesc": "R", "zoning_code": null, "zoning_description": null } ], "truncated": false, "credits": 1 }, { "index": 2, "input": { "longitude": -78.627, "latitude": 35.7999 }, "status": "ok", "records": [ { "id": "37183-676db8ae68362b7a3685", "korzy_id": "37183-676db8ae68362b7a3685", "parcelid": "1714066205", "alternate_parcel_number": "0364254", "statefp": "37", "geoid": "37183", "countyname": "Wake", "updated": "2026-05-17", "parceladdr": "714 MORDECAI TOWNE PL", "parcelcity": "RALEIGH", "situs_state": null, "situs_zip": "27604", "municipality": null, "subdivision": null, "legal_description": "LO4 MORDECAI TOWNS AT COURTLAND DRIVE BM2007 -01069", "longitude": -78.62700116632315, "latitude": 35.79988145, "taxacres": 0.03, "land_use_code": "RHS", "usedesc": "R", "zoning_code": null, "zoning_description": null } ], "truncated": false, "credits": 1 } ], "credits": { "charged": 3, "refunded": 0 }, "credits_url": "/v1/fields#attribution", "request_id": "7fcb2798-ac8e-49ab-96e4-1fd30d093461" } }, "enrich_owner": { "summary": "Owner and sale fields (abbreviated)", "value": { "fields": [ "korzy_id", "parcelid", "alternate_parcel_number" ], "results": [ { "index": 0, "input": { "address": "1600 Glenarm Pl, Denver, CO" }, "status": "ok", "records": [ { "id": "08031-00608646b37458fef5b5", "korzy_id": "08031-00608646b37458fef5b5", "parcelid": "0234610034000", "alternate_parcel_number": null, "statefp": "08", "geoid": "08031", "countyname": "Denver", "updated": "2026-04-21", "saledate": "2018-07-11", "saleamt": 131000000, "last_sale_document": null, "owner_name": "EXAMPLE HOLDINGS LLC", "owner_mailing_address": "100 EXAMPLE ST, SAMPLE CITY, ST 00000" }, { "id": "08031-38ea02a85c11fd253b1c", "korzy_id": "08031-38ea02a85c11fd253b1c", "parcelid": "0234610035000", "alternate_parcel_number": null, "statefp": "08", "geoid": "08031", "countyname": "Denver", "updated": "2026-04-21", "saledate": "2018-07-11", "saleamt": 131000000, "last_sale_document": null, "owner_name": "EXAMPLE HOLDINGS LLC", "owner_mailing_address": "100 EXAMPLE ST, SAMPLE CITY, ST 00000" }, { "id": "08031-5b4cf0a0a15d0ff3a944", "korzy_id": "08031-5b4cf0a0a15d0ff3a944", "parcelid": "0234610034998", "alternate_parcel_number": null, "statefp": "08", "geoid": "08031", "countyname": "Denver", "updated": "2026-04-21", "saledate": "2026-06-15", "saleamt": 0, "last_sale_document": null } ], "truncated": false, "credits": 2 } ], "credits": { "charged": 2, "refunded": 0 }, "credits_url": "/v1/fields#attribution", "request_id": "fdce65b2-8dc1-48a2-8d8f-dfa134d28acf" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "description": "- `owner_data_unavailable`: Owner fields are not available for your organization. Not charged.\n- Your credential lacks the required scope (`api:read` for `/v1`, `mcp:read` for MCP).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "description": "- `invalid_request`: The body is missing a field, has an unknown one or a value out of range. `detail` says which.\n- `invalid_json`: A POST body is not a JSON object. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-korzy-credits": { "min": 1, "max": 50, "per_item": 1, "owner_multiplier": 2, "max_items": 25 } } }, "/v1/records/{id}": { "get": { "operationId": "getRecordsId", "tags": [ "Records" ], "summary": "One record by ID, with its provenance", "description": "One record by ID, with its provenance.\n\nCost: 1 credit.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "An `id` from a lookup or enrich response, URL-encoded. See [record IDs](https://korzy.co/docs/reference/#record-ids).", "schema": { "type": "string" }, "examples": { "record_parcel": { "summary": "A parcel", "value": "37183-676db8ae68362b7a3685" }, "record_plant": { "summary": "A power plant", "value": "plant:57695" } } } ], "responses": { "200": { "description": "One record by ID, with its provenance", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "type", "record", "provenance", "credits", "request_id" ], "properties": { "id": { "type": "string", "description": "The ID you asked for." }, "type": { "type": "string", "description": "One of `parcel`, `power_plant`, `data_center`, `utility`, `energy_facility`, `grid_capacity`, `property`, `poi`." }, "record": { "type": "object", "description": "The record. Parcel and property records never include owner fields." }, "provenance": { "type": "array", "description": "Dataset, `as_of` date and data version of each source." }, "credits": { "type": "object", "description": "`charged` and `refunded`: what this request spent and what was given back (failed items or sections)." }, "request_id": { "type": "string", "description": "ID of this request. Include it in support requests." } } }, "examples": { "record_parcel": { "summary": "A parcel (abbreviated)", "value": { "id": "37183-676db8ae68362b7a3685", "type": "parcel", "record": { "id": "37183-676db8ae68362b7a3685", "bldgsqft": 2393, "countyname": "Wake", "latitude": 35.79988145, "longitude": -78.62700116632315, "korzy_id": "37183-676db8ae68362b7a3685", "parceladdr": "714 MORDECAI TOWNE PL", "parcelcity": "RALEIGH", "parcelid": "1714066205", "saleamt": 740000, "saledate": "2025-07-10", "statefp": "37", "taxacres": 0.03, "totalvalue": 662832, "updated": "2026-05-17", "usedesc": "R", "yearbuilt": 2009, "situs_state": null, "situs_zip": "27604", "municipality": null, "subdivision": null, "legal_description": "LO4 MORDECAI TOWNS AT COURTLAND DRIVE BM2007 -01069", "land_use_code": "RHS", "zoning_code": null, "zoning_description": null, "alternate_parcel_number": "0364254", "living_area_sqft": null, "building_count": 1, "tax_year": null, "land_value_usd": 135000, "improvement_value_usd": 527832, "assessed_value_usd": null, "market_value_usd": null, "taxable_value_usd": null, "tax_amount_usd": null, "last_sale_document": "Deed Book/Page 019954/02049", "geoid": "37183", "parcelid2": "0364254", "ogparcelid": "1714066205", "taxacctnum": null }, "provenance": [ { "dataset": "parcels", "as_of": null, "data_version": null } ], "credits": { "charged": 1, "refunded": 0 }, "credits_url": "/v1/fields#attribution", "request_id": "c3ea32bf-0db7-4173-be4a-51cdca989f57" } }, "record_plant": { "summary": "A power plant (abbreviated)", "value": { "id": "plant:57695", "type": "power_plant", "record": { "plant_id": "57695", "plant_name": "Topaz Solar Farm", "utility_id": "59874", "utility_name": "Topaz Solar Farms LLC", "state": "CA", "county": "San Luis Obispo", "street_address": "10400 Helios Way", "city": "Santa Margarita", "zip_code": "93453", "latitude": 35.405556, "longitude": -120.068611, "nerc_region": "WECC", "balancing_authority_code": "CISO", "balancing_authority_name": "California Independent System Operator", "grid_owner": "Pacific Gas & Electric Co", "grid_owner_id": "14328", "grid_voltage_kv": 230, "grid_voltage_2_kv": null, "grid_voltage_3_kv": null, "water_source": null, "natural_gas_ldc": null, "gas_pipeline_1": null, "gas_pipeline_2": null, "gas_pipeline_3": null, "pipeline_notes": null, "report_year": 2025, "data_version": "2b27929d26cc1da9ad6a530da1cac6718cd8496098ee560c4d47cfffd96d08ba", "source_workbook": "[internal reference]", "source_sheet": "Plant", "state_fips": "06", "coordinate_status": "valid", "generators": [ { "plant_id": "57695", "plant_name": "Topaz Solar Farm", "utility_id": "59874", "utility_name": "Topaz Solar Farms LLC", "state": "CA", "county": "San Luis Obispo", "generator_id": "TPZ1", "technology": "Solar Photovoltaic", "prime_mover": "PV", "energy_source_1": "SUN", "energy_source_2": null, "status_code": "OP", "nameplate_capacity_mw": 129.8, "summer_capacity_mw": 129.8, "winter_capacity_mw": 129.8, "minimum_load_mw": null, "operating_month": 4, "operating_year": 2013, "planned_retirement_month": null, "planned_retirement_year": null, "retirement_month": null, "retirement_year": null, "planned_operating_month": null, "planned_operating_year": null, "lmp_node": null, "wholesale_location": null, "chp_code": "N", "report_year": 2025, "data_version": "2b27929d26cc1da9ad6a530da1cac6718cd8496098ee560c4d47cfffd96d08ba", "source_workbook": "[internal reference]", "source_sheet": "Operable", "state_fips": "06", "status": "operating", "inventory_group": "operable", "date_issues": [], "fuel_group": "solar" }, { "plant_id": "57695", "plant_name": "Topaz Solar Farm", "utility_id": "59874", "utility_name": "Topaz Solar Farms LLC", "state": "CA", "county": "San Luis Obispo", "generator_id": "TPZ2", "technology": "Solar Photovoltaic", "prime_mover": "PV", "energy_source_1": "SUN", "energy_source_2": null, "status_code": "OP", "nameplate_capacity_mw": 151.2, "summer_capacity_mw": 151.2, "winter_capacity_mw": 151.2, "minimum_load_mw": null, "operating_month": 6, "operating_year": 2013, "planned_retirement_month": null, "planned_retirement_year": null, "retirement_month": null, "retirement_year": null, "planned_operating_month": null, "planned_operating_year": null, "lmp_node": null, "wholesale_location": null, "chp_code": "N", "report_year": 2025, "data_version": "2b27929d26cc1da9ad6a530da1cac6718cd8496098ee560c4d47cfffd96d08ba", "source_workbook": "[internal reference]", "source_sheet": "Operable", "state_fips": "06", "status": "operating", "inventory_group": "operable", "date_issues": [], "fuel_group": "solar" }, { "plant_id": "57695", "plant_name": "Topaz Solar Farm", "utility_id": "59874", "utility_name": "Topaz Solar Farms LLC", "state": "CA", "county": "San Luis Obispo", "generator_id": "TPZ3", "technology": "Solar Photovoltaic", "prime_mover": "PV", "energy_source_1": "SUN", "energy_source_2": null, "status_code": "OP", "nameplate_capacity_mw": 102.1, "summer_capacity_mw": 102.1, "winter_capacity_mw": 102.1, "minimum_load_mw": null, "operating_month": 1, "operating_year": 2014, "planned_retirement_month": null, "planned_retirement_year": null, "retirement_month": null, "retirement_year": null, "planned_operating_month": null, "planned_operating_year": null, "lmp_node": null, "wholesale_location": null, "chp_code": "N", "report_year": 2025, "data_version": "2b27929d26cc1da9ad6a530da1cac6718cd8496098ee560c4d47cfffd96d08ba", "source_workbook": "[internal reference]", "source_sheet": "Operable", "state_fips": "06", "status": "operating", "inventory_group": "operable", "date_issues": [], "fuel_group": "solar" } ], "generator_count": 5, "generators_truncated": false, "energy": { "latest_period": "2026-08", "observations": [ { "dataset": "plant_monthly", "plant_id": "57695", "generator_id": null, "region": "CA", "period": "2026-08", "metric": "fuel_consumption_mmbtu", "value": 422341, "unit": "MMBtu", "dimensions_json": "{\"aggregation\": \"plant_fuel\", \"data_status\": \"preliminary\", \"fuel\": \"SUN\", \"nuclear_unit_id\": \".\", \"prime_mover\": \"PV\", \"source_sheet\": \"Page 1 Generation and Fuel Data\", \"source_workbook\": \"[internal reference]\"}", "data_version": "50ec141c118547dc0219356171476319e45b5ea382446bda617752a5635e4e91", "source_date": "2026-08", "retrieved_at": "2026-10-31T10:30:48.104651+00:00" }, { "dataset": "plant_monthly", "plant_id": "57695", "generator_id": null, "region": "CA", "period": "2026-08", "metric": "fuel_consumption_quantity", "value": 0, "unit": "source fuel units", "dimensions_json": "{\"aggregation\": \"plant_fuel\", \"data_status\": \"preliminary\", \"fuel\": \"SUN\", \"nuclear_unit_id\": \".\", \"prime_mover\": \"PV\", \"source_sheet\": \"Page 1 Generation and Fuel Data\", \"source_workbook\": \"[internal reference]\"}", "data_version": "50ec141c118547dc0219356171476319e45b5ea382446bda617752a5635e4e91", "source_date": "2026-08", "retrieved_at": "2026-10-31T10:30:48.104651+00:00" }, { "dataset": "plant_monthly", "plant_id": "57695", "generator_id": null, "region": "CA", "period": "2026-08", "metric": "generation_mwh", "value": 123781, "unit": "MWh", "dimensions_json": "{\"aggregation\": \"plant_fuel\", \"data_status\": \"preliminary\", \"fuel\": \"SUN\", \"nuclear_unit_id\": \".\", \"prime_mover\": \"PV\", \"source_sheet\": \"Page 1 Generation and Fuel Data\", \"source_workbook\": \"[internal reference]\"}", "data_version": "50ec141c118547dc0219356171476319e45b5ea382446bda617752a5635e4e91", "source_date": "2026-08", "retrieved_at": "2026-10-31T10:30:48.104651+00:00" } ], "truncated": false } }, "provenance": [ { "dataset": "power_plants", "as_of": null, "data_version": "2b27929d26cc1da9ad6a530da1cac6718cd8496098ee560c4d47cfffd96d08ba" }, { "dataset": "energy_operations", "as_of": "2026-11-05", "data_version": "20261105T054519113327Z" } ], "credits": { "charged": 1, "refunded": 0 }, "credits_url": "/v1/fields#attribution", "request_id": "39927bef-3c40-4635-8e30-cb8523b0b817" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "description": "- `record_not_found`: No record has this ID. Refunded.\n- `use_v1`: Unknown route. Paths under `/api` are not part of the public API; use `/v1`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "description": "- `invalid_id`: The ID is not in a known form. Refunded.\n- `invalid_json`: A POST body is not a JSON object. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-korzy-credits": { "min": 1, "max": 1 } } }, "/v1/ask": { "post": { "operationId": "postAsk", "tags": [ "Ask" ], "summary": "Answer a question about an address or point, with citations to the records used", "description": "Answer a question about an address or point, with citations to the records used.\n\nSend the question with exactly one location: `address`, or `longitude` and `latitude`.\n\nCost: 10 credits.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "longitude": { "type": "number", "maximum": 180.0, "minimum": -180.0 }, "latitude": { "type": "number", "maximum": 85.0, "minimum": -85.0 }, "address": { "type": "string", "maxLength": 160, "minLength": 3 }, "question": { "type": "string", "maxLength": 1000, "minLength": 3 } }, "additionalProperties": false, "type": "object", "required": [ "question" ] }, "examples": { "ask": { "summary": "Example request", "value": { "question": "Does this property have public water and sewer, and are there cleanup sites nearby?", "address": "2304 Hillsborough St, Raleigh, NC" } } } } }, "required": true, "description": "- `question` (required): The question, 3–1,000 characters.\n- `address`: A street address, 3–160 characters, such as `714 Mordecai Towne Pl, Raleigh, NC`. Must match exactly; including the state gives the most precise match.\n- `longitude`: Longitude, −180 to 180. Send with `latitude` instead of `address`.\n- `latitude`: Latitude, −85 to 85." }, "responses": { "200": { "description": "Answer a question about an address or point, with citations to the records used", "content": { "application/json": { "schema": { "type": "object", "required": [ "answer", "citations", "model", "usage", "credits", "request_id" ], "properties": { "answer": { "type": "string", "description": "The answer, with inline citations such as `[c1]`." }, "citations": { "type": "array", "description": "Each citation: `ref` (`c1`), `id` of the record, and `field`, `source` and `as_of` where known." }, "model": { "type": "string", "description": "The model that wrote the answer." }, "usage": { "type": "object", "description": "Token counts, model calls and data lookups used." }, "credits": { "type": "integer", "description": "Credits this question spent, as a number (unlike other routes, not a `charged`/`refunded` object)." }, "request_id": { "type": "string", "description": "ID of this request. Include it in support requests." } } }, "examples": { "ask": { "summary": "Production response (abbreviated)", "value": { "answer": "Yes.\n\n- Public water: the parcel is within the Raleigh, City of water boundary [c2].\n- Public sewer: the parcel is within the Neuse River Resource Recovery Facility sewer boundary [c3].\n\nNearby cleanup sites:\n- Brownfield site “FORMER TAO AUTO,” about 1.74 km away [c11].\n- Superfund NPL site “North Carolina State University (Lot 86, Farm Unit #1),” about 4.56 km away [c10].\n\nKorzy data does not say whether those cleanup sites affect the parcel itself.", "citations": [ { "ref": "c2", "id": "utility:water:29943", "field": null, "source": "water, sewer, treatment", "as_of": null }, { "ref": "c3", "id": "utility:sewer:2161", "field": null, "source": "water, sewer, treatment", "as_of": null }, { "ref": "c11", "id": "poi:brownfields:brownfields:records:5117", "field": null, "source": "superfund_sites, superfund_npl, brownfields, protected_areas, critical_habitat_areas, critical_habitat_lines, air_quality_areas, flood_hazard, wetlands", "as_of": null } ], "model": "example-model", "usage": { "input_tokens": 4215, "cached_input_tokens": 4096, "output_tokens": 163, "reasoning_tokens": 41, "model_calls": 1, "tool_calls": 0 }, "credits": 10, "request_id": "7a2558aa-cd4a-4847-9f9f-ce063bbfe1d7" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "description": "- `address_not_found`: No exact match for the address. Refunded.\n- `use_v1`: Unknown route. Paths under `/api` are not part of the public API; use `/v1`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "description": "- `invalid_request`: The body is missing a field, has an unknown one or a value out of range. `detail` says which.\n- `invalid_json`: A POST body is not a JSON object. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "- `ask_rate_limited`: Your organization reached its Ask limit for the minute or day. Wait for `Retry-After`.\n- Rate limit or monthly credits reached. Wait for `Retry-After`; monthly exhaustion also includes `resets_at`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "description": "- `ask_location_unavailable`: The location was found but could not be loaded for the answer. Refunded; retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "- `ask_capacity`: Ask is at capacity for today. Refunded; try again later.\n- `ask_unavailable`: Ask is temporarily unavailable. Refunded.\n- Temporarily unavailable. Refunded; retry after `Retry-After` with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-korzy-credits": { "min": 10, "max": 10 } } }, "/v1/ask/stream": { "post": { "operationId": "postAskStream", "tags": [ "Ask" ], "summary": "The same answer as server-sent events, as it is written", "description": "The same answer as server-sent events, as it is written.\n\nThe response is `text/event-stream`. Each event is `event: ` and one line of JSON `data`; see [stream events](https://korzy.co/docs/reference/#ask-events).\n\nIf the stream ends without a `done` event (an `error`, a dropped connection or a cancel), the request is refunded.\n\nCost: 10 credits.", "requestBody": { "content": { "application/json": { "schema": { "properties": { "longitude": { "type": "number", "maximum": 180.0, "minimum": -180.0 }, "latitude": { "type": "number", "maximum": 85.0, "minimum": -85.0 }, "address": { "type": "string", "maxLength": 160, "minLength": 3 }, "question": { "type": "string", "maxLength": 1000, "minLength": 3 } }, "additionalProperties": false, "type": "object", "required": [ "question" ] }, "examples": { "ask_stream": { "summary": "Example request", "value": { "question": "Does this property have public water and sewer, and are there cleanup sites nearby?", "address": "2304 Hillsborough St, Raleigh, NC" } } } } }, "required": true, "description": "- `question` (required): The question, 3–1,000 characters.\n- `address`: A street address, 3–160 characters, such as `714 Mordecai Towne Pl, Raleigh, NC`. Must match exactly; including the state gives the most precise match.\n- `longitude`: Longitude, −180 to 180. Send with `latitude` instead of `address`.\n- `latitude`: Latitude, −85 to 85." }, "responses": { "200": { "description": "The same answer as server-sent events, as it is written. Server-sent events, each `event: ` with one line of JSON `data`:\n\n- `start`: `request_id`, `model`.\n- `step`: A data lookup the answer made: `step`, `tool`, `arguments`, `status` (`ok` or `error`) and `ms`.\n- `delta`: `text`: the next piece of the answer.\n- `done`: The same object `/v1/ask` returns. Credits are kept only when `done` arrives.\n- `error`: `code` and `detail`; the stream then ends and the request is refunded.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "description": "- `address_not_found`: No exact match for the address. Refunded.\n- `use_v1`: Unknown route. Paths under `/api` are not part of the public API; use `/v1`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "description": "- `invalid_request`: The body is missing a field, has an unknown one or a value out of range. `detail` says which.\n- `invalid_json`: A POST body is not a JSON object. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "- `ask_rate_limited`: Your organization reached its Ask limit for the minute or day.\n- Rate limit or monthly credits reached. Wait for `Retry-After`; monthly exhaustion also includes `resets_at`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "$ref": "#/components/responses/Error500" }, "502": { "description": "- `ask_location_unavailable`: Sent as an `error` event after `start`: the location could not be loaded. Refunded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "- `ask_capacity`: Ask is at capacity for today. Refunded; try again later.\n- `ask_unavailable`: Ask is temporarily unavailable. Refunded.\n- Temporarily unavailable. Refunded; retry after `Retry-After` with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } } }, "x-korzy-credits": { "min": 10, "max": 10 } } }, "/v1/support": { "post": { "operationId": "postSupport", "tags": [ "Support" ], "summary": "Open a support request", "description": "Open a support request. We read every one.\n\nCost: Free.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportInput" }, "examples": { "support": { "summary": "Example request", "value": { "type": "feature", "message": "Example request captured for the Korzy API docs; no action needed.", "context": { "endpoint": "/v1/lookup" } } } } } }, "required": true, "description": "- `type` (required): `feature`, `data` or `bug`.\n- `message` (required): What happened or what you need, 1–4,000 characters.\n- `context`: Optional: `request_id`, `korzy_id`, `longitude`, `latitude` and `endpoint` the message is about." }, "responses": { "201": { "description": "Open a support request", "content": { "application/json": { "schema": { "type": "object", "required": [ "ticket_id", "status", "created_at", "credits", "request_id" ], "properties": { "ticket_id": { "type": "string", "description": "ID of the request." }, "status": { "type": "string", "description": "`open`." }, "created_at": { "type": "string", "description": "When it was opened (ISO 8601)." }, "credits": { "type": "object", "description": "`charged` and `refunded`: what this request spent and what was given back (failed items or sections)." }, "request_id": { "type": "string", "description": "ID of this request. Include it in support requests." } } }, "examples": { "support": { "summary": "Production response (abbreviated)", "value": { "ticket_id": "8550bff4-622f-4146-abf5-258109c9bee2", "status": "open", "created_at": "2026-11-05T21:13:00.283Z", "credits": { "charged": 0, "refunded": 0 }, "credits_url": "/v1/fields#attribution", "request_id": "082817b9-2595-4c3d-96bc-2a8d386c787d" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "description": "- `invalid_request`: The body is missing a field, has an unknown one or a value out of range. `detail` says which.\n- `invalid_json`: A POST body is not a JSON object. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "- `support_rate_limited`: Your organization reached its support limit for the hour or day.\n- Rate limit or monthly credits reached. Wait for `Retry-After`; monthly exhaustion also includes `resets_at`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-korzy-credits": { "min": 0, "max": 0 } } }, "/v1/fields": { "get": { "operationId": "getFields", "tags": [ "Fields" ], "summary": "Lookup sections, enrich fields, groups and presets, record types, credits, limits and data attribution", "description": "Lookup sections, enrich fields, groups and presets, record types, credits, limits and data attribution.\n\nCost: Free.", "responses": { "200": { "description": "Lookup sections, enrich fields, groups and presets, record types, credits, limits and data attribution", "content": { "application/json": { "schema": { "type": "object", "required": [ "lookup", "enrich", "records", "ask", "support", "attribution", "credits", "request_id" ], "properties": { "lookup": { "type": "object", "description": "`credits` and `sections`: each with `name`, `credits`, `description`, key `data` fields and `coverage`." }, "enrich": { "type": "object", "description": "`max_items`, `item_credits`, `owner_multiplier`, `groups` (each with `owner` and typed `fields`), `presets` and `default_preset`." }, "records": { "type": "object", "description": "`credits` and `types`, each with its `id_format`." }, "ask": { "type": "object", "description": "`credits` and `limits`." }, "support": { "type": "object", "description": "Credits and limits." }, "attribution": { "type": "array", "description": "Data sources and the attribution each requires." }, "credits": { "type": "object", "description": "`charged` and `refunded`: what this request spent and what was given back (failed items or sections)." }, "request_id": { "type": "string", "description": "ID of this request. Include it in support requests." } } }, "examples": { "fields": { "summary": "Production response (abbreviated)", "value": { "lookup": { "credits": 1, "max_parcels": 20, "sections": [ { "name": "utilities", "credits": 1, "description": "Mapped water and sewer service areas covering the point and wastewater treatment plants within 50 km.", "data": [ { "name": "water", "type": "array", "unit": null }, { "name": "sewer", "type": "array", "unit": null }, { "name": "treatment_plants[].distance_km", "type": "number", "unit": "km" } ], "coverage": "Mapped service areas where published; no match means unknown." }, { "name": "environment", "credits": 1, "description": "Environmental areas at the point and cleanup sites within 10 km (up to 5 per layer), with flood hazard and wetland mapping coverage.", "data": [ { "name": "matches", "type": "object", "unit": null }, { "name": "nearby[].distance_km", "type": "number", "unit": "km" }, { "name": "coverage", "type": "object", "unit": null } ], "coverage": "Coverage is mapped, unknown or unavailable; never a finding that the point is outside a flood zone or wetland." }, { "name": "logistics", "credits": 1, "description": "Rail, ports, terminals, waterways, roads, bridges and warehouses within 25 km (up to 5 per layer).", "data": [ { "name": "nearby[].distance_km", "type": "number", "unit": "km" } ], "coverage": "Straight-line distances to mapped geometry, not routed distances." } ] }, "enrich": { "max_items": 25, "item_credits": 1, "max_records_per_item": 20, "groups": [ { "name": "identity", "owner": false, "fields": [ { "name": "korzy_id", "type": "string", "unit": null, "description": "Korzy parcel ID (stable across releases)" }, { "name": "parcelid", "type": "string", "unit": null, "description": "Source parcel number (APN)" }, { "name": "alternate_parcel_number", "type": "string", "unit": null, "description": "Alternate source parcel number" } ] }, { "name": "address", "owner": false, "fields": [ { "name": "parceladdr", "type": "string", "unit": null, "description": "Situs (property) street address" }, { "name": "parcelcity", "type": "string", "unit": null, "description": "Situs city" }, { "name": "situs_state", "type": "string", "unit": null, "description": "Situs state" } ] }, { "name": "location", "owner": false, "fields": [ { "name": "longitude", "type": "number", "unit": "degrees", "description": "Longitude of a point inside the parcel" }, { "name": "latitude", "type": "number", "unit": "degrees", "description": "Latitude of a point inside the parcel" } ] } ], "presets": { "basic": [ "identity", "address", "location" ], "standard": [ "identity", "address", "location" ], "owner": [ "identity", "address", "location" ] }, "default_preset": "standard" }, "records": { "credits": 1, "types": [ { "type": "parcel", "id_format": " for served counties, otherwise parcel:@//; use the ID exactly as returned", "example": "37183-676db8ae68362b7a3685" }, { "type": "power_plant", "id_format": "plant:", "example": "plant:3" }, { "type": "data_center", "id_format": "datacenter:" } ] }, "ask": { "credits": 10, "limits": { "per_org_per_minute": 6, "per_org_per_day": 200 } }, "support": { "credits": 0, "types": [ "feature", "data", "bug" ], "message_max": 4000, "limits": { "per_org_per_hour": 10, "per_org_per_day": 30 } }, "fields": { "credits": 0 }, "attribution": [ { "license": "ODbL-1.0" }, {}, { "license": "ODbL-1.0" } ], "credits": { "charged": 0, "refunded": 0 }, "credits_url": "/v1/fields#attribution", "request_id": "c42fb0f6-865a-43d5-8c7b-4bacca9de2aa" } } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "x-korzy-credits": { "min": 0, "max": 0 } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "description": "What went wrong, as a message." }, "code": { "type": "string", "description": "Machine-readable reason." } } }, "LookupInput": { "properties": { "longitude": { "type": "number", "maximum": 180.0, "minimum": -180.0, "description": "Longitude, −180 to 180. Send with `latitude` instead of `address`." }, "latitude": { "type": "number", "maximum": 85.0, "minimum": -85.0, "description": "Latitude, −85 to 85." }, "address": { "type": "string", "maxLength": 160, "minLength": 3, "description": "A street address, 3–160 characters, such as `714 Mordecai Towne Pl, Raleigh, NC`. Must match exactly; including the state gives the most precise match." }, "sections": { "items": { "type": "string", "enum": [ "utilities", "environment", "logistics", "datacenters", "power", "grid", "terrain", "boundary" ] }, "type": "array", "maxItems": 8, "description": "Any of `utilities`, `environment`, `logistics`, `datacenters`, `power`, `grid`, `terrain`, `boundary`. Default: none, parcels only." } }, "additionalProperties": false, "type": "object" }, "EnrichInput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/EnrichItem" }, "type": "array", "maxItems": 25, "minItems": 1, "description": "1–25 items, each `{\"address\": …}`, `{\"longitude\": …, \"latitude\": …}` or `{\"korzy_id\": …}`." }, "fields": { "items": { "type": "string", "maxLength": 60, "minLength": 1 }, "type": "array", "maxItems": 48, "minItems": 1, "description": "Field names or groups (`identity`, `address`, `location`, `land`, `building`, `value`, `sale`, `owner`); see [Enrich fields](https://korzy.co/docs/reference/#enrich-fields). Not with `preset`." }, "preset": { "type": "string", "maxLength": 40, "minLength": 1, "description": "`basic`, `standard`, `owner`. Default `standard` when neither `fields` nor `preset` is sent.", "enum": [ "basic", "standard", "owner" ], "default": "standard" } }, "additionalProperties": false, "type": "object", "required": [ "items" ] }, "EnrichItem": { "properties": { "longitude": { "type": "number", "maximum": 180.0, "minimum": -180.0 }, "latitude": { "type": "number", "maximum": 85.0, "minimum": -85.0 }, "address": { "type": "string", "maxLength": 160, "minLength": 3 }, "korzy_id": { "type": "string", "maxLength": 200, "minLength": 1 } }, "additionalProperties": false, "type": "object" }, "SupportInput": { "properties": { "type": { "type": "string", "enum": [ "feature", "data", "bug" ], "description": "`feature`, `data` or `bug`." }, "message": { "type": "string", "maxLength": 4000, "minLength": 1, "description": "What happened or what you need, 1–4,000 characters." }, "context": { "$ref": "#/components/schemas/SupportContext", "description": "Optional: `request_id`, `korzy_id`, `longitude`, `latitude` and `endpoint` the message is about." } }, "additionalProperties": false, "type": "object", "required": [ "type", "message" ] }, "SupportContext": { "properties": { "request_id": { "type": "string", "maxLength": 100 }, "korzy_id": { "type": "string", "maxLength": 160 }, "longitude": { "type": "number", "maximum": 180.0, "minimum": -180.0 }, "latitude": { "type": "number", "maximum": 85.0, "minimum": -85.0 }, "endpoint": { "type": "string", "maxLength": 100 } }, "additionalProperties": false, "type": "object" } }, "responses": { "Error401": { "description": "Missing, malformed, revoked or expired credential.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error402": { "description": "`subscription_required`: Your account has no active subscription. Choose a plan on your account page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "Your credential lacks the required scope (`api:read` for `/v1`, `mcp:read` for MCP).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "`use_v1`: Unknown route. Paths under `/api` are not part of the public API; use `/v1`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "error_record_not_found": { "summary": "Unknown record", "value": { "detail": "No record with this ID", "code": "record_not_found" } } } } } }, "Error405": { "description": "The route doesn’t accept this HTTP method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error413": { "description": "The JSON body is larger than 64 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error422": { "description": "`invalid_json`: A POST body is not a JSON object. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "error_invalid_request": { "summary": "Invalid body", "value": { "detail": "address: String should have at least 3 characters", "code": "invalid_request" } } } } } }, "Error429": { "description": "Rate limit or monthly credits reached. Wait for `Retry-After`; monthly exhaustion also includes `resets_at`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } }, "Error500": { "description": "Something went wrong on our side. Refunded; retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error503": { "description": "Temporarily unavailable. Refunded; retry after `Retry-After` with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A Korzy API key from https://app.korzy.co/account, or an OAuth access token from Korzy sign-in. Every route needs `api:read`." } } } }