{"openapi":"3.1.0","info":{"title":"Matthews API","version":"1.0.0","description":"Matthews API provides access to location intelligence data for Matthews clients. This is a subset of the AlphaMap API with specific endpoints.\n\n## Authentication\n\nAll API endpoints require authentication via API key. Include your API key in the request header:\n\n```\nx-api-key: your_api_key_here\n```\n\nOr use Bearer token format:\n\n```\nAuthorization: Bearer your_api_key_here\n```","contact":{"name":"AlphaMap Team","email":"support@alphamap.com"}},"servers":[{"url":"/","description":"Production API server"}],"tags":[{"name":"area","description":"Area-based analytics including demographics, coverage, and mobility"},{"name":"boundaries","description":"Geographic boundary data and information"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for authentication. Contact AlphaMap to obtain your key."}},"schemas":{},"parameters":{}},"paths":{"/boundaries/states/{id}":{"get":{"tags":["boundaries"],"description":"Get the polygon geometry for a state by its ID","parameters":[{"schema":{"type":"string","description":"State ID (two-letter code)","example":"CA"},"required":true,"description":"State ID (two-letter code)","name":"id","in":"path"}],"responses":{"200":{"description":"Get the polygon geometry for a state by its ID","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"}],"description":"State boundary as a GeoJSON Polygon or MultiPolygon or null if not found"}}}},"404":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"State with ID \"XX\" not found","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid state ID format","issues":[{"path":["id"],"message":"Expected string"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/boundaries/counties/{id}":{"get":{"tags":["boundaries"],"description":"Get the polygon geometry and metadata for a county by its FIPS code","parameters":[{"schema":{"type":"string","description":"County FIPS code","example":"06037"},"required":true,"description":"County FIPS code","name":"id","in":"path"}],"responses":{"200":{"description":"Get county boundary polygon with metadata (name, state)","content":{"application/json":{"schema":{"type":"object","properties":{"polygon":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"}]},"meta":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"stateName":{"type":"string","nullable":true}},"required":["id","name","stateName"]}},"required":["polygon","meta"]},"example":{"polygon":{"type":"Polygon","coordinates":[[[-118.6681,33.7037],[-118.6681,34.8233],[-117.6462,34.8233],[-117.6462,33.7037],[-118.6681,33.7037]]]},"meta":{"id":"06037","name":"Los Angeles County"}}}}},"404":{"description":"County not found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"County with FIPS code \"00000\" not found","code":"NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/boundaries/zipcodes/{id}":{"get":{"tags":["boundaries"],"description":"Get the polygon geometry for a zipcode by its ID","parameters":[{"schema":{"type":"string","description":"Zipcode","example":"90210"},"required":true,"description":"Zipcode","name":"id","in":"path"}],"responses":{"200":{"description":"Get the polygon geometry for a zipcode by its ID","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"}],"description":"Zipcode boundary as a GeoJSON Polygon or MultiPolygon"},"example":{"type":"Polygon","coordinates":[[[-118.4081,34.0901],[-118.4081,34.1021],[-118.3961,34.1021],[-118.3961,34.0901],[-118.4081,34.0901]]]}}}},"404":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Zipcode with ID \"00000\" not found","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid zipcode ID format","issues":[{"path":["id"],"message":"Expected string"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/boundaries/h3/{id}":{"get":{"tags":["boundaries"],"description":"Get the polygon geometry for an H3 cell by its index","parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 index","example":"8a2a1072b59ffff"},"required":true,"description":"H3 index","name":"id","in":"path"}],"responses":{"200":{"description":"Get the polygon geometry for an H3 index","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"H3 cell boundary as a GeoJSON Polygon"},"example":{"type":"Polygon","coordinates":[[[-118.291994,34.021851],[-118.291994,34.031851],[-118.281994,34.031851],[-118.281994,34.021851],[-118.291994,34.021851]]]}}}},"422":{"description":"Invalid H3 index or validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid H3 index format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"Internal server error"}}}}}}},"/boundaries/cities/{id}":{"get":{"tags":["boundaries"],"description":"Get the polygon geometry and metadata for a city by its ID","parameters":[{"schema":{"type":"string","description":"City ID","example":"4805000"},"required":true,"description":"City ID","name":"id","in":"path"}],"responses":{"200":{"description":"Get city boundary polygon with metadata (name, state, area)","content":{"application/json":{"schema":{"type":"object","properties":{"polygon":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"}]},"meta":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"fullName":{"type":"string"},"stateName":{"type":"string","nullable":true},"landAreaSqMiles":{"type":"number","nullable":true}},"required":["id","name","fullName","stateName","landAreaSqMiles"]}},"required":["polygon","meta"]},"example":{"polygon":{"type":"MultiPolygon","coordinates":[[[[[-97.9384,30.137],[-97.9384,30.5168],[-97.5683,30.5168],[-97.5683,30.137],[-97.9384,30.137]]]]]},"meta":{"id":"4805000","name":"Austin","fullName":"Austin city","stateName":"Texas","landAreaSqMiles":327.52}}}}},"404":{"description":"City not found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"City with ID \"0000000\" not found","code":"NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"Internal server error"}}}}}}},"/boundaries/census-blocks/{id}":{"get":{"tags":["boundaries"],"description":"Get the polygon geometry for a census block by its ID","parameters":[{"schema":{"type":"string","description":"Census Block ID","example":"600109501001001"},"required":true,"description":"Census Block ID","name":"id","in":"path"}],"responses":{"200":{"description":"Get the multi-polygon geometry for a census block by its ID","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"}],"description":"Census Block boundary as a GeoJSON Polygon or MultiPolygon or null if not found"},"example":{"type":"Polygon","coordinates":[[[-118.291994,34.021851],[-118.291994,34.031851],[-118.281994,34.031851],[-118.281994,34.021851],[-118.291994,34.021851]]]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid request","code":"INVALID_REQUEST"}}}},"404":{"description":"Census block not found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Census block with ID 600109501001001 not found","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid census block ID format"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"Internal server error"}}}}}}},"/boundaries/census-block-groups/{id}":{"get":{"tags":["boundaries"],"description":"Get the polygon geometry for a census block group by its ID","parameters":[{"schema":{"type":"string","description":"Census Block Group ID","example":"484530001011"},"required":true,"description":"Census Block Group ID","name":"id","in":"path"}],"responses":{"200":{"description":"Get census block group boundary geometry","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"geometry":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"}]},"properties":{"type":"object","properties":{"id":{"type":"string"},"stateName":{"type":"string","nullable":true},"countyName":{"type":"string","nullable":true},"tractName":{"type":"string","nullable":true},"blockGroupName":{"type":"string","nullable":true}},"required":["id","stateName","countyName","tractName","blockGroupName"]}},"required":["type","geometry","properties"]},"example":{"type":"Feature","geometry":{"type":"Polygon","coordinates":[[[-97.7431,30.2672],[-97.7431,30.2772],[-97.7331,30.2772],[-97.7331,30.2672],[-97.7431,30.2672]]]},"properties":{"id":"484530001011","stateName":null,"countyName":null,"tractName":null,"blockGroupName":null}}}}},"404":{"description":"Census block group not found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Census block group with ID \"000000000000\" not found","code":"NOT_FOUND"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"Internal server error"}}}}}}},"/area/demographics/age":{"post":{"tags":["area","demographics"],"description":"Get age demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves age breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"age_0_4":{"type":"integer","minimum":0,"description":"Population aged 0-4"},"age_5_9":{"type":"integer","minimum":0,"description":"Population aged 5-9"},"age_10_14":{"type":"integer","minimum":0,"description":"Population aged 10-14"},"age_15_17":{"type":"integer","minimum":0,"description":"Population aged 15-17"},"age_18_20":{"type":"integer","minimum":0,"description":"Population aged 18-20"},"age_21_24":{"type":"integer","minimum":0,"description":"Population aged 21-24"},"age_25_34":{"type":"integer","minimum":0,"description":"Population aged 25-34"},"age_35_44":{"type":"integer","minimum":0,"description":"Population aged 35-44"},"age_45_54":{"type":"integer","minimum":0,"description":"Population aged 45-54"},"age_55_64":{"type":"integer","minimum":0,"description":"Population aged 55-64"},"age_65_74":{"type":"integer","minimum":0,"description":"Population aged 65-74"},"age_75_84":{"type":"integer","minimum":0,"description":"Population aged 75-84"},"age_85_plus":{"type":"integer","minimum":0,"description":"Population aged 85+"}},"required":["age_0_4","age_5_9","age_10_14","age_15_17","age_18_20","age_21_24","age_25_34","age_35_44","age_45_54","age_55_64","age_65_74","age_75_84","age_85_plus"],"description":"Current year age breakdown"},"forecast":{"type":"object","properties":{"age_0_4":{"type":"integer","minimum":0,"description":"Population aged 0-4"},"age_5_9":{"type":"integer","minimum":0,"description":"Population aged 5-9"},"age_10_14":{"type":"integer","minimum":0,"description":"Population aged 10-14"},"age_15_17":{"type":"integer","minimum":0,"description":"Population aged 15-17"},"age_18_20":{"type":"integer","minimum":0,"description":"Population aged 18-20"},"age_21_24":{"type":"integer","minimum":0,"description":"Population aged 21-24"},"age_25_34":{"type":"integer","minimum":0,"description":"Population aged 25-34"},"age_35_44":{"type":"integer","minimum":0,"description":"Population aged 35-44"},"age_45_54":{"type":"integer","minimum":0,"description":"Population aged 45-54"},"age_55_64":{"type":"integer","minimum":0,"description":"Population aged 55-64"},"age_65_74":{"type":"integer","minimum":0,"description":"Population aged 65-74"},"age_75_84":{"type":"integer","minimum":0,"description":"Population aged 75-84"},"age_85_plus":{"type":"integer","minimum":0,"description":"Population aged 85+"}},"required":["age_0_4","age_5_9","age_10_14","age_15_17","age_18_20","age_21_24","age_25_34","age_35_44","age_45_54","age_55_64","age_65_74","age_75_84","age_85_plus"],"description":"Five-year forecast age breakdown"},"nationalAvg":{"type":"object","properties":{"age_0_4":{"type":"integer","minimum":0,"description":"Population aged 0-4"},"age_5_9":{"type":"integer","minimum":0,"description":"Population aged 5-9"},"age_10_14":{"type":"integer","minimum":0,"description":"Population aged 10-14"},"age_15_17":{"type":"integer","minimum":0,"description":"Population aged 15-17"},"age_18_20":{"type":"integer","minimum":0,"description":"Population aged 18-20"},"age_21_24":{"type":"integer","minimum":0,"description":"Population aged 21-24"},"age_25_34":{"type":"integer","minimum":0,"description":"Population aged 25-34"},"age_35_44":{"type":"integer","minimum":0,"description":"Population aged 35-44"},"age_45_54":{"type":"integer","minimum":0,"description":"Population aged 45-54"},"age_55_64":{"type":"integer","minimum":0,"description":"Population aged 55-64"},"age_65_74":{"type":"integer","minimum":0,"description":"Population aged 65-74"},"age_75_84":{"type":"integer","minimum":0,"description":"Population aged 75-84"},"age_85_plus":{"type":"integer","minimum":0,"description":"Population aged 85+"}},"required":["age_0_4","age_5_9","age_10_14","age_15_17","age_18_20","age_21_24","age_25_34","age_35_44","age_45_54","age_55_64","age_65_74","age_75_84","age_85_plus"],"description":"National average age breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"age_0_4":5000,"age_5_9":4500,"age_10_14":4200,"age_15_17":2800,"age_18_20":3100,"age_21_24":4200,"age_25_34":8500,"age_35_44":7200,"age_45_54":6800,"age_55_64":5900,"age_65_74":4500,"age_75_84":2800,"age_85_plus":1500},"forecast":{"age_0_4":5200,"age_5_9":4600,"age_10_14":4300,"age_15_17":2900,"age_18_20":3200,"age_21_24":4400,"age_25_34":8800,"age_35_44":7500,"age_45_54":7000,"age_55_64":6200,"age_65_74":4800,"age_75_84":3000,"age_85_plus":1600},"nationalAvg":{"age_0_4":4800,"age_5_9":4300,"age_10_14":4000,"age_15_17":2600,"age_18_20":2900,"age_21_24":3900,"age_25_34":8000,"age_35_44":6800,"age_45_54":6400,"age_55_64":5500,"age_65_74":4200,"age_75_84":2600,"age_85_plus":1400}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/consumer-spend":{"post":{"tags":["area","demographics"],"description":"Get consumer-spend demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves household expenditure data across spending categories for an area using block group overlap aggregation","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"total_expenditure":{"type":"number","minimum":0,"description":"Total household expenditure"},"food":{"type":"number","minimum":0,"description":"Food spending"},"alcohol_beverages":{"type":"number","minimum":0,"description":"Alcoholic beverages spending"},"housing":{"type":"number","minimum":0,"description":"Housing spending"},"apparel":{"type":"number","minimum":0,"description":"Apparel and services spending"},"transportation":{"type":"number","minimum":0,"description":"Transportation spending"},"health":{"type":"number","minimum":0,"description":"Healthcare spending"},"entertainment":{"type":"number","minimum":0,"description":"Entertainment spending"},"personal_care":{"type":"number","minimum":0,"description":"Personal care spending"},"reading":{"type":"number","minimum":0,"description":"Reading materials spending"},"education":{"type":"number","minimum":0,"description":"Education spending"},"tobacco":{"type":"number","minimum":0,"description":"Tobacco products spending"},"miscellaneous":{"type":"number","minimum":0,"description":"Miscellaneous spending"},"cash_contributions":{"type":"number","minimum":0,"description":"Cash contributions"},"insurance_pensions":{"type":"number","minimum":0,"description":"Insurance and pensions spending"},"total_retail":{"type":"number","minimum":0,"description":"Total retail spending"},"total_non_retail":{"type":"number","minimum":0,"description":"Total non-retail spending"}},"required":["total_expenditure","food","alcohol_beverages","housing","apparel","transportation","health","entertainment","personal_care","reading","education","tobacco","miscellaneous","cash_contributions","insurance_pensions","total_retail","total_non_retail"],"description":"Current year consumer spending breakdown"},"forecast":{"type":"object","properties":{"total_expenditure":{"type":"number","minimum":0,"description":"Total household expenditure"},"food":{"type":"number","minimum":0,"description":"Food spending"},"alcohol_beverages":{"type":"number","minimum":0,"description":"Alcoholic beverages spending"},"housing":{"type":"number","minimum":0,"description":"Housing spending"},"apparel":{"type":"number","minimum":0,"description":"Apparel and services spending"},"transportation":{"type":"number","minimum":0,"description":"Transportation spending"},"health":{"type":"number","minimum":0,"description":"Healthcare spending"},"entertainment":{"type":"number","minimum":0,"description":"Entertainment spending"},"personal_care":{"type":"number","minimum":0,"description":"Personal care spending"},"reading":{"type":"number","minimum":0,"description":"Reading materials spending"},"education":{"type":"number","minimum":0,"description":"Education spending"},"tobacco":{"type":"number","minimum":0,"description":"Tobacco products spending"},"miscellaneous":{"type":"number","minimum":0,"description":"Miscellaneous spending"},"cash_contributions":{"type":"number","minimum":0,"description":"Cash contributions"},"insurance_pensions":{"type":"number","minimum":0,"description":"Insurance and pensions spending"},"total_retail":{"type":"number","minimum":0,"description":"Total retail spending"},"total_non_retail":{"type":"number","minimum":0,"description":"Total non-retail spending"}},"required":["total_expenditure","food","alcohol_beverages","housing","apparel","transportation","health","entertainment","personal_care","reading","education","tobacco","miscellaneous","cash_contributions","insurance_pensions","total_retail","total_non_retail"],"description":"Five-year forecast consumer spending breakdown"},"nationalAvg":{"type":"object","properties":{"total_expenditure":{"type":"number","minimum":0,"description":"Total household expenditure"},"food":{"type":"number","minimum":0,"description":"Food spending"},"alcohol_beverages":{"type":"number","minimum":0,"description":"Alcoholic beverages spending"},"housing":{"type":"number","minimum":0,"description":"Housing spending"},"apparel":{"type":"number","minimum":0,"description":"Apparel and services spending"},"transportation":{"type":"number","minimum":0,"description":"Transportation spending"},"health":{"type":"number","minimum":0,"description":"Healthcare spending"},"entertainment":{"type":"number","minimum":0,"description":"Entertainment spending"},"personal_care":{"type":"number","minimum":0,"description":"Personal care spending"},"reading":{"type":"number","minimum":0,"description":"Reading materials spending"},"education":{"type":"number","minimum":0,"description":"Education spending"},"tobacco":{"type":"number","minimum":0,"description":"Tobacco products spending"},"miscellaneous":{"type":"number","minimum":0,"description":"Miscellaneous spending"},"cash_contributions":{"type":"number","minimum":0,"description":"Cash contributions"},"insurance_pensions":{"type":"number","minimum":0,"description":"Insurance and pensions spending"},"total_retail":{"type":"number","minimum":0,"description":"Total retail spending"},"total_non_retail":{"type":"number","minimum":0,"description":"Total non-retail spending"}},"required":["total_expenditure","food","alcohol_beverages","housing","apparel","transportation","health","entertainment","personal_care","reading","education","tobacco","miscellaneous","cash_contributions","insurance_pensions","total_retail","total_non_retail"],"description":"National average consumer spending breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"total_expenditure":500000000,"food":50000000},"forecast":{"total_expenditure":500000000,"food":50000000},"nationalAvg":{"total_expenditure":65000,"food":8200}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/population":{"post":{"tags":["area","demographics"],"description":"Get population demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves population metrics (current and forecast) for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"population":{"type":"integer","description":"Current year total population"},"workdayPopulation":{"type":"integer","nullable":true,"description":"Daytime/workday population estimate (null, use workday-population module for this)"}},"required":["population","workdayPopulation"],"description":"Current year population metrics"},"forecast":{"type":"object","properties":{"population":{"type":"integer","description":"Five-year forecast total population"},"growthPercentage":{"type":"number","description":"Projected population growth percentage"}},"required":["population","growthPercentage"],"description":"Five-year forecast population metrics"},"nationalAvg":{"type":"object","properties":{"population":{"type":"integer","description":"National average population for this area size"}},"required":["population"],"description":"National average population metrics"}},"required":["current","forecast","nationalAvg"],"description":"Population data for a geographic area"},"example":{"current":{"population":50000,"workdayPopulation":75000},"forecast":{"population":53500,"growthPercentage":7},"nationalAvg":{"population":23456}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/race-ethnicity":{"post":{"tags":["area","demographics"],"description":"Get race/ethnicity demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves ethnicity breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"white":{"type":"integer","minimum":0,"description":"White population"},"black":{"type":"integer","minimum":0,"description":"Black/African American population"},"asian":{"type":"integer","minimum":0,"description":"Asian population"},"hispanic":{"type":"integer","minimum":0,"description":"Hispanic/Latino population"},"other":{"type":"integer","minimum":0,"description":"Other races/ethnicities"}},"required":["white","black","asian","hispanic","other"],"description":"Current year ethnicity breakdown"},"forecast":{"type":"object","properties":{"white":{"type":"integer","minimum":0,"description":"White population"},"black":{"type":"integer","minimum":0,"description":"Black/African American population"},"asian":{"type":"integer","minimum":0,"description":"Asian population"},"hispanic":{"type":"integer","minimum":0,"description":"Hispanic/Latino population"},"other":{"type":"integer","minimum":0,"description":"Other races/ethnicities"}},"required":["white","black","asian","hispanic","other"],"description":"Five-year forecast ethnicity breakdown"},"nationalAvg":{"type":"object","properties":{"white":{"type":"integer","minimum":0,"description":"White population"},"black":{"type":"integer","minimum":0,"description":"Black/African American population"},"asian":{"type":"integer","minimum":0,"description":"Asian population"},"hispanic":{"type":"integer","minimum":0,"description":"Hispanic/Latino population"},"other":{"type":"integer","minimum":0,"description":"Other races/ethnicities"}},"required":["white","black","asian","hispanic","other"],"description":"National average ethnicity breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"white":25000,"black":8000,"asian":7000,"hispanic":15000,"other":3000},"forecast":{"white":26000,"black":8500,"asian":7500,"hispanic":16000,"other":3200},"nationalAvg":{"white":1850,"black":390,"asian":175,"hispanic":580,"other":125}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/households":{"post":{"tags":["area","demographics"],"description":"Get household demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves total household counts for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"integer","minimum":0,"description":"Current year total households"},"forecast":{"type":"integer","minimum":0,"description":"Five-year forecast total households"},"nationalAvg":{"type":"integer","minimum":0,"description":"National average total households"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"total_households":10000},"forecast":{"total_households":10500},"nationalAvg":{"total_households":450}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/household-income":{"post":{"tags":["area","demographics"],"description":"Get household-income demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves household income distribution for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"distribution":{"type":"object","properties":{"less_than_15k":{"type":"integer","minimum":0,"description":"Households earning less than $15k"},"from_15k_to_25k":{"type":"integer","minimum":0,"description":"Households earning $15k-$25k"},"from_25k_to_35k":{"type":"integer","minimum":0,"description":"Households earning $25k-$35k"},"from_35k_to_50k":{"type":"integer","minimum":0,"description":"Households earning $35k-$50k"},"from_50k_to_75k":{"type":"integer","minimum":0,"description":"Households earning $50k-$75k"},"from_75k_to_100k":{"type":"integer","minimum":0,"description":"Households earning $75k-$100k"},"from_100k_to_125k":{"type":"integer","minimum":0,"description":"Households earning $100k-$125k"},"from_125k_to_150k":{"type":"integer","minimum":0,"description":"Households earning $125k-$150k"},"from_150k_to_200k":{"type":"integer","minimum":0,"description":"Households earning $150k-$200k"},"from_200k_to_250k":{"type":"integer","minimum":0,"description":"Households earning $200k-$250k"},"from_250k_to_500k":{"type":"integer","minimum":0,"description":"Households earning $250k-$500k"},"more_than_500k":{"type":"integer","minimum":0,"description":"Households earning $500k+"}},"required":["less_than_15k","from_15k_to_25k","from_25k_to_35k","from_35k_to_50k","from_50k_to_75k","from_75k_to_100k","from_100k_to_125k","from_125k_to_150k","from_150k_to_200k","from_200k_to_250k","from_250k_to_500k","more_than_500k"],"description":"Current year income distribution"},"median":{"type":"number","minimum":0,"description":"Median household income"},"average":{"type":"number","minimum":0,"description":"Average (mean) household income"}},"required":["distribution","median","average"]},"forecast":{"type":"object","properties":{"distribution":{"type":"object","properties":{"less_than_15k":{"type":"integer","minimum":0,"description":"Households earning less than $15k"},"from_15k_to_25k":{"type":"integer","minimum":0,"description":"Households earning $15k-$25k"},"from_25k_to_35k":{"type":"integer","minimum":0,"description":"Households earning $25k-$35k"},"from_35k_to_50k":{"type":"integer","minimum":0,"description":"Households earning $35k-$50k"},"from_50k_to_75k":{"type":"integer","minimum":0,"description":"Households earning $50k-$75k"},"from_75k_to_100k":{"type":"integer","minimum":0,"description":"Households earning $75k-$100k"},"from_100k_to_125k":{"type":"integer","minimum":0,"description":"Households earning $100k-$125k"},"from_125k_to_150k":{"type":"integer","minimum":0,"description":"Households earning $125k-$150k"},"from_150k_to_200k":{"type":"integer","minimum":0,"description":"Households earning $150k-$200k"},"from_200k_to_250k":{"type":"integer","minimum":0,"description":"Households earning $200k-$250k"},"from_250k_to_500k":{"type":"integer","minimum":0,"description":"Households earning $250k-$500k"},"more_than_500k":{"type":"integer","minimum":0,"description":"Households earning $500k+"}},"required":["less_than_15k","from_15k_to_25k","from_25k_to_35k","from_35k_to_50k","from_50k_to_75k","from_75k_to_100k","from_100k_to_125k","from_125k_to_150k","from_150k_to_200k","from_200k_to_250k","from_250k_to_500k","more_than_500k"],"description":"Five-year forecast income distribution"},"median":{"type":"number","minimum":0,"description":"Forecast median household income"},"average":{"type":"number","minimum":0,"description":"Forecast average household income"}},"required":["distribution","median","average"]},"nationalAvg":{"type":"object","properties":{"distribution":{"type":"object","properties":{"less_than_15k":{"type":"integer","minimum":0,"description":"Households earning less than $15k"},"from_15k_to_25k":{"type":"integer","minimum":0,"description":"Households earning $15k-$25k"},"from_25k_to_35k":{"type":"integer","minimum":0,"description":"Households earning $25k-$35k"},"from_35k_to_50k":{"type":"integer","minimum":0,"description":"Households earning $35k-$50k"},"from_50k_to_75k":{"type":"integer","minimum":0,"description":"Households earning $50k-$75k"},"from_75k_to_100k":{"type":"integer","minimum":0,"description":"Households earning $75k-$100k"},"from_100k_to_125k":{"type":"integer","minimum":0,"description":"Households earning $100k-$125k"},"from_125k_to_150k":{"type":"integer","minimum":0,"description":"Households earning $125k-$150k"},"from_150k_to_200k":{"type":"integer","minimum":0,"description":"Households earning $150k-$200k"},"from_200k_to_250k":{"type":"integer","minimum":0,"description":"Households earning $200k-$250k"},"from_250k_to_500k":{"type":"integer","minimum":0,"description":"Households earning $250k-$500k"},"more_than_500k":{"type":"integer","minimum":0,"description":"Households earning $500k+"}},"required":["less_than_15k","from_15k_to_25k","from_25k_to_35k","from_35k_to_50k","from_50k_to_75k","from_75k_to_100k","from_100k_to_125k","from_125k_to_150k","from_150k_to_200k","from_200k_to_250k","from_250k_to_500k","more_than_500k"],"description":"National average income distribution"},"median":{"type":"number","minimum":0,"description":"National average median household income"},"average":{"type":"number","minimum":0,"description":"National average mean household income"}},"required":["distribution","median","average"]}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"distribution":{"less_than_15k":1200,"from_15k_to_25k":1800,"from_25k_to_35k":2100,"from_35k_to_50k":2500,"from_50k_to_75k":3200,"from_75k_to_100k":2800,"from_100k_to_125k":1900,"from_125k_to_150k":1400,"from_150k_to_200k":1100,"from_200k_to_250k":600,"from_250k_to_500k":400,"more_than_500k":100},"median":75000,"average":82000},"forecast":{"distribution":{"less_than_15k":1100,"from_15k_to_25k":1700,"from_25k_to_35k":2000,"from_35k_to_50k":2400,"from_50k_to_75k":3100,"from_75k_to_100k":2900,"from_100k_to_125k":2000,"from_125k_to_150k":1500,"from_150k_to_200k":1200,"from_200k_to_250k":650,"from_250k_to_500k":450,"more_than_500k":120},"median":78000,"average":85000},"nationalAvg":{"distribution":{"less_than_15k":980,"from_15k_to_25k":1500,"from_25k_to_35k":1900,"from_35k_to_50k":2300,"from_50k_to_75k":3000,"from_75k_to_100k":2700,"from_100k_to_125k":1800,"from_125k_to_150k":1300,"from_150k_to_200k":1000,"from_200k_to_250k":550,"from_250k_to_500k":380,"more_than_500k":90},"median":69000,"average":76000}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/housing-units":{"post":{"tags":["area","demographics"],"description":"Get housing units demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves housing unit counts for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Total housing units"},"vacant":{"type":"integer","minimum":0,"description":"Vacant housing units"},"occupied":{"type":"integer","minimum":0,"description":"Occupied housing units (calculated)"}},"required":["total","vacant","occupied"]},"forecast":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"Forecast total housing units"},"vacant":{"type":"integer","minimum":0,"description":"Forecast vacant housing units"},"occupied":{"type":"integer","minimum":0,"description":"Forecast occupied housing units (calculated)"}},"required":["total","vacant","occupied"]},"nationalAvg":{"type":"object","properties":{"total":{"type":"integer","minimum":0,"description":"National average total housing units"},"vacant":{"type":"integer","minimum":0,"description":"National average vacant housing units"},"occupied":{"type":"integer","minimum":0,"description":"National average occupied housing units (calculated)"}},"required":["total","vacant","occupied"]}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"total_housing_units":12000},"forecast":{"total_housing_units":12600},"nationalAvg":{"total_housing_units":480}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/gender":{"post":{"tags":["area","demographics"],"description":"Get gender demographics (male/female distribution with current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves gender breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"male":{"type":"object","properties":{"current":{"type":"integer","description":"Current year count"},"forecast":{"type":"integer","description":"Five-year forecast count"}},"required":["current","forecast"],"description":"Male population"},"female":{"type":"object","properties":{"current":{"type":"integer","description":"Current year count"},"forecast":{"type":"integer","description":"Five-year forecast count"}},"required":["current","forecast"],"description":"Female population"},"nationalAvg":{"type":"object","properties":{"male":{"type":"integer","description":"National average male population"},"female":{"type":"integer","description":"National average female population"}},"required":["male","female"],"description":"National average gender distribution"}},"required":["male","female","nationalAvg"],"description":"Gender breakdown for a geographic area"},"example":{"male":{"current":24500,"forecast":25800},"female":{"current":25500,"forecast":27700},"nationalAvg":{"male":{"current":1650,"forecast":1700},"female":{"current":1700,"forecast":1750}}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/marital-status":{"post":{"tags":["area","demographics"],"description":"Get marital-status demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves marital status breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"never_married":{"type":"integer","minimum":0,"description":"Never married population"},"married_spouse_present":{"type":"integer","minimum":0,"description":"Married with spouse present"},"married_spouse_absent":{"type":"integer","minimum":0,"description":"Married with spouse absent"},"divorced":{"type":"integer","minimum":0,"description":"Divorced population"},"widowed":{"type":"integer","minimum":0,"description":"Widowed population"}},"required":["never_married","married_spouse_present","married_spouse_absent","divorced","widowed"],"description":"Current year marital status breakdown"},"forecast":{"type":"object","properties":{"never_married":{"type":"integer","minimum":0,"description":"Never married population"},"married_spouse_present":{"type":"integer","minimum":0,"description":"Married with spouse present"},"married_spouse_absent":{"type":"integer","minimum":0,"description":"Married with spouse absent"},"divorced":{"type":"integer","minimum":0,"description":"Divorced population"},"widowed":{"type":"integer","minimum":0,"description":"Widowed population"}},"required":["never_married","married_spouse_present","married_spouse_absent","divorced","widowed"],"description":"Five-year forecast marital status breakdown"},"nationalAvg":{"type":"object","properties":{"never_married":{"type":"integer","minimum":0,"description":"Never married population"},"married_spouse_present":{"type":"integer","minimum":0,"description":"Married with spouse present"},"married_spouse_absent":{"type":"integer","minimum":0,"description":"Married with spouse absent"},"divorced":{"type":"integer","minimum":0,"description":"Divorced population"},"widowed":{"type":"integer","minimum":0,"description":"Widowed population"}},"required":["never_married","married_spouse_present","married_spouse_absent","divorced","widowed"],"description":"National average marital status breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"married":6000,"single":4000},"forecast":{"married":6000,"single":4000},"nationalAvg":{"married":240,"single":160}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/value-of-owner-occupied-housing-units":{"post":{"tags":["area","demographics"],"description":"Get value-owner-occupied-housing-units demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves housing value statistics for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"median":{"type":"number","minimum":0,"description":"Median home value"},"average":{"type":"number","minimum":0,"description":"Average (mean) home value"}},"required":["median","average"]},"forecast":{"type":"object","properties":{"median":{"type":"number","minimum":0,"description":"Forecast median home value"},"average":{"type":"number","minimum":0,"description":"Forecast average home value"}},"required":["median","average"]},"nationalAvg":{"type":"object","properties":{"median":{"type":"number","minimum":0,"description":"National average median home value"},"average":{"type":"number","minimum":0,"description":"National average mean home value"}},"required":["median","average"]}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"median_value":350000,"average_value":380000},"forecast":{"median_value":350000,"average_value":380000},"nationalAvg":{"median_value":280000,"average_value":310000}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/types-of-housing-units":{"post":{"tags":["area","demographics"],"description":"Get types-of-housing-units demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves housing type breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"single_family_detached":{"type":"integer","minimum":0,"description":"Single-family detached homes"},"single_family_attached":{"type":"integer","minimum":0,"description":"Single-family attached homes"},"units_2":{"type":"integer","minimum":0,"description":"2-unit buildings"},"units_3_4":{"type":"integer","minimum":0,"description":"3-4 unit buildings"},"units_5_19":{"type":"integer","minimum":0,"description":"5-19 unit buildings"},"units_20_49":{"type":"integer","minimum":0,"description":"20-49 unit buildings"},"units_50_plus":{"type":"integer","minimum":0,"description":"50+ unit buildings"},"other":{"type":"integer","minimum":0,"description":"Other housing types (mobile homes, etc.)"}},"required":["single_family_detached","single_family_attached","units_2","units_3_4","units_5_19","units_20_49","units_50_plus","other"],"description":"Current year housing types breakdown"},"forecast":{"type":"object","properties":{"single_family_detached":{"type":"integer","minimum":0,"description":"Single-family detached homes"},"single_family_attached":{"type":"integer","minimum":0,"description":"Single-family attached homes"},"units_2":{"type":"integer","minimum":0,"description":"2-unit buildings"},"units_3_4":{"type":"integer","minimum":0,"description":"3-4 unit buildings"},"units_5_19":{"type":"integer","minimum":0,"description":"5-19 unit buildings"},"units_20_49":{"type":"integer","minimum":0,"description":"20-49 unit buildings"},"units_50_plus":{"type":"integer","minimum":0,"description":"50+ unit buildings"},"other":{"type":"integer","minimum":0,"description":"Other housing types (mobile homes, etc.)"}},"required":["single_family_detached","single_family_attached","units_2","units_3_4","units_5_19","units_20_49","units_50_plus","other"],"description":"Five-year forecast housing types breakdown"},"nationalAvg":{"type":"object","properties":{"single_family_detached":{"type":"integer","minimum":0,"description":"Single-family detached homes"},"single_family_attached":{"type":"integer","minimum":0,"description":"Single-family attached homes"},"units_2":{"type":"integer","minimum":0,"description":"2-unit buildings"},"units_3_4":{"type":"integer","minimum":0,"description":"3-4 unit buildings"},"units_5_19":{"type":"integer","minimum":0,"description":"5-19 unit buildings"},"units_20_49":{"type":"integer","minimum":0,"description":"20-49 unit buildings"},"units_50_plus":{"type":"integer","minimum":0,"description":"50+ unit buildings"},"other":{"type":"integer","minimum":0,"description":"Other housing types (mobile homes, etc.)"}},"required":["single_family_detached","single_family_attached","units_2","units_3_4","units_5_19","units_20_49","units_50_plus","other"],"description":"National average housing types breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"single_family":5000,"multi_family":3000},"forecast":{"single_family":5000,"multi_family":3000},"nationalAvg":{"single_family":310,"multi_family":170}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/education":{"post":{"tags":["area","demographics"],"description":"Get education demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves educational attainment breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"less_than_9th_grade":{"type":"integer","minimum":0,"description":"Population with less than 9th grade education"},"some_high_school":{"type":"integer","minimum":0,"description":"Population with some high school"},"high_school_graduate":{"type":"integer","minimum":0,"description":"Population with high school diploma/GED"},"some_college":{"type":"integer","minimum":0,"description":"Population with some college, no degree"},"associates_degree":{"type":"integer","minimum":0,"description":"Population with associate degree"},"bachelors_degree":{"type":"integer","minimum":0,"description":"Population with bachelor degree"},"masters_degree":{"type":"integer","minimum":0,"description":"Population with master degree"},"professional_degree":{"type":"integer","minimum":0,"description":"Population with professional degree"},"doctorate_degree":{"type":"integer","minimum":0,"description":"Population with doctorate degree"}},"required":["less_than_9th_grade","some_high_school","high_school_graduate","some_college","associates_degree","bachelors_degree","masters_degree","professional_degree","doctorate_degree"],"description":"Current year education breakdown"},"forecast":{"type":"object","properties":{"less_than_9th_grade":{"type":"integer","minimum":0,"description":"Population with less than 9th grade education"},"some_high_school":{"type":"integer","minimum":0,"description":"Population with some high school"},"high_school_graduate":{"type":"integer","minimum":0,"description":"Population with high school diploma/GED"},"some_college":{"type":"integer","minimum":0,"description":"Population with some college, no degree"},"associates_degree":{"type":"integer","minimum":0,"description":"Population with associate degree"},"bachelors_degree":{"type":"integer","minimum":0,"description":"Population with bachelor degree"},"masters_degree":{"type":"integer","minimum":0,"description":"Population with master degree"},"professional_degree":{"type":"integer","minimum":0,"description":"Population with professional degree"},"doctorate_degree":{"type":"integer","minimum":0,"description":"Population with doctorate degree"}},"required":["less_than_9th_grade","some_high_school","high_school_graduate","some_college","associates_degree","bachelors_degree","masters_degree","professional_degree","doctorate_degree"],"description":"Five-year forecast education breakdown"},"nationalAvg":{"type":"object","properties":{"less_than_9th_grade":{"type":"integer","minimum":0,"description":"Population with less than 9th grade education"},"some_high_school":{"type":"integer","minimum":0,"description":"Population with some high school"},"high_school_graduate":{"type":"integer","minimum":0,"description":"Population with high school diploma/GED"},"some_college":{"type":"integer","minimum":0,"description":"Population with some college, no degree"},"associates_degree":{"type":"integer","minimum":0,"description":"Population with associate degree"},"bachelors_degree":{"type":"integer","minimum":0,"description":"Population with bachelor degree"},"masters_degree":{"type":"integer","minimum":0,"description":"Population with master degree"},"professional_degree":{"type":"integer","minimum":0,"description":"Population with professional degree"},"doctorate_degree":{"type":"integer","minimum":0,"description":"Population with doctorate degree"}},"required":["less_than_9th_grade","some_high_school","high_school_graduate","some_college","associates_degree","bachelors_degree","masters_degree","professional_degree","doctorate_degree"],"description":"National average education breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"bachelors_degree":8000,"high_school_graduate":12000},"forecast":{"bachelors_degree":8000,"high_school_graduate":12000},"nationalAvg":{"bachelors_degree":320,"high_school_graduate":450}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/labor-force":{"post":{"tags":["area","demographics"],"description":"Get labor-force demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves labor force status breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"employed":{"type":"integer","minimum":0,"description":"Employed population"},"unemployed":{"type":"integer","minimum":0,"description":"Unemployed population"},"armed_forces":{"type":"integer","minimum":0,"description":"Population in armed forces"},"not_in_labor_force":{"type":"integer","minimum":0,"description":"Population not in labor force"}},"required":["employed","unemployed","armed_forces","not_in_labor_force"],"description":"Current year labor force breakdown"},"forecast":{"type":"object","properties":{"employed":{"type":"integer","minimum":0,"description":"Employed population"},"unemployed":{"type":"integer","minimum":0,"description":"Unemployed population"},"armed_forces":{"type":"integer","minimum":0,"description":"Population in armed forces"},"not_in_labor_force":{"type":"integer","minimum":0,"description":"Population not in labor force"}},"required":["employed","unemployed","armed_forces","not_in_labor_force"],"description":"Five-year forecast labor force breakdown"},"nationalAvg":{"type":"object","properties":{"employed":{"type":"integer","minimum":0,"description":"Employed population"},"unemployed":{"type":"integer","minimum":0,"description":"Unemployed population"},"armed_forces":{"type":"integer","minimum":0,"description":"Population in armed forces"},"not_in_labor_force":{"type":"integer","minimum":0,"description":"Population not in labor force"}},"required":["employed","unemployed","armed_forces","not_in_labor_force"],"description":"National average labor force breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"employed":45000,"unemployed":2000},"forecast":{"employed":45000,"unemployed":2000},"nationalAvg":{"employed":950,"unemployed":45}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/transportation":{"post":{"tags":["area","demographics"],"description":"Get transportation demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves commute method breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"drive_alone":{"type":"integer","minimum":0,"description":"Drive alone to work"},"carpool":{"type":"integer","minimum":0,"description":"Carpool to work"},"public_transit":{"type":"integer","minimum":0,"description":"Public transportation"},"walk":{"type":"integer","minimum":0,"description":"Walk to work"},"bike":{"type":"integer","minimum":0,"description":"Bike to work"},"work_from_home":{"type":"integer","minimum":0,"description":"Work from home"},"other":{"type":"integer","minimum":0,"description":"Other transportation methods"}},"required":["drive_alone","carpool","public_transit","walk","bike","work_from_home","other"],"description":"Current year transportation breakdown"},"forecast":{"type":"object","properties":{"drive_alone":{"type":"integer","minimum":0,"description":"Drive alone to work"},"carpool":{"type":"integer","minimum":0,"description":"Carpool to work"},"public_transit":{"type":"integer","minimum":0,"description":"Public transportation"},"walk":{"type":"integer","minimum":0,"description":"Walk to work"},"bike":{"type":"integer","minimum":0,"description":"Bike to work"},"work_from_home":{"type":"integer","minimum":0,"description":"Work from home"},"other":{"type":"integer","minimum":0,"description":"Other transportation methods"}},"required":["drive_alone","carpool","public_transit","walk","bike","work_from_home","other"],"description":"Five-year forecast transportation breakdown"},"nationalAvg":{"type":"object","properties":{"drive_alone":{"type":"integer","minimum":0,"description":"Drive alone to work"},"carpool":{"type":"integer","minimum":0,"description":"Carpool to work"},"public_transit":{"type":"integer","minimum":0,"description":"Public transportation"},"walk":{"type":"integer","minimum":0,"description":"Walk to work"},"bike":{"type":"integer","minimum":0,"description":"Bike to work"},"work_from_home":{"type":"integer","minimum":0,"description":"Work from home"},"other":{"type":"integer","minimum":0,"description":"Other transportation methods"}},"required":["drive_alone","carpool","public_transit","walk","bike","work_from_home","other"],"description":"National average transportation breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"drove_alone":20000,"carpooled":3000},"forecast":{"drove_alone":20000,"carpooled":3000},"nationalAvg":{"drove_alone":720,"carpooled":110}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/travel-time":{"post":{"tags":["area","demographics"],"description":"Get travel-time demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves commute travel time breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"less_than_15_min":{"type":"integer","minimum":0,"description":"Commute time less than 15 minutes"},"from_15_to_29_min":{"type":"integer","minimum":0,"description":"Commute time 15-29 minutes"},"from_30_to_44_min":{"type":"integer","minimum":0,"description":"Commute time 30-44 minutes"},"from_45_to_59_min":{"type":"integer","minimum":0,"description":"Commute time 45-59 minutes"},"more_than_60_min":{"type":"integer","minimum":0,"description":"Commute time 60+ minutes"}},"required":["less_than_15_min","from_15_to_29_min","from_30_to_44_min","from_45_to_59_min","more_than_60_min"],"description":"Current year travel time breakdown"},"forecast":{"type":"object","properties":{"less_than_15_min":{"type":"integer","minimum":0,"description":"Commute time less than 15 minutes"},"from_15_to_29_min":{"type":"integer","minimum":0,"description":"Commute time 15-29 minutes"},"from_30_to_44_min":{"type":"integer","minimum":0,"description":"Commute time 30-44 minutes"},"from_45_to_59_min":{"type":"integer","minimum":0,"description":"Commute time 45-59 minutes"},"more_than_60_min":{"type":"integer","minimum":0,"description":"Commute time 60+ minutes"}},"required":["less_than_15_min","from_15_to_29_min","from_30_to_44_min","from_45_to_59_min","more_than_60_min"],"description":"Five-year forecast travel time breakdown"},"nationalAvg":{"type":"object","properties":{"less_than_15_min":{"type":"integer","minimum":0,"description":"Commute time less than 15 minutes"},"from_15_to_29_min":{"type":"integer","minimum":0,"description":"Commute time 15-29 minutes"},"from_30_to_44_min":{"type":"integer","minimum":0,"description":"Commute time 30-44 minutes"},"from_45_to_59_min":{"type":"integer","minimum":0,"description":"Commute time 45-59 minutes"},"more_than_60_min":{"type":"integer","minimum":0,"description":"Commute time 60+ minutes"}},"required":["less_than_15_min","from_15_to_29_min","from_30_to_44_min","from_45_to_59_min","more_than_60_min"],"description":"National average travel time breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"less_than_15_min":5000,"from_15_to_29_min":8000},"forecast":{"less_than_15_min":5000,"from_15_to_29_min":8000},"nationalAvg":{"less_than_15_min":200,"from_15_to_29_min":320}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/population-by-occupation":{"post":{"tags":["area","demographics"],"description":"Get population-by-occupation demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves employment by occupation category breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"management":{"type":"integer","minimum":0,"description":"Management occupations"},"business_operations":{"type":"integer","minimum":0,"description":"Business and financial operations"},"computer_mathematical":{"type":"integer","minimum":0,"description":"Computer and mathematical"},"architecture_engineering":{"type":"integer","minimum":0,"description":"Architecture and engineering"},"life_physical_social_science":{"type":"integer","minimum":0,"description":"Life, physical, and social science"},"community_social_services":{"type":"integer","minimum":0,"description":"Community and social services"},"legal":{"type":"integer","minimum":0,"description":"Legal occupations"},"education_training_library":{"type":"integer","minimum":0,"description":"Education, training, and library"},"arts_design_entertainment_sports_media":{"type":"integer","minimum":0,"description":"Arts, design, entertainment, sports, media"},"healthcare_practitioners_technical":{"type":"integer","minimum":0,"description":"Healthcare practitioners and technical"},"healthcare_support":{"type":"integer","minimum":0,"description":"Healthcare support"},"protective_service":{"type":"integer","minimum":0,"description":"Protective service"},"food_preparation_serving":{"type":"integer","minimum":0,"description":"Food preparation and serving"},"building_grounds_cleaning_maintenance":{"type":"integer","minimum":0,"description":"Building and grounds cleaning and maintenance"},"personal_care_service":{"type":"integer","minimum":0,"description":"Personal care and service"},"sales":{"type":"integer","minimum":0,"description":"Sales occupations"},"office_administrative_support":{"type":"integer","minimum":0,"description":"Office and administrative support"},"farming_fishing_forestry":{"type":"integer","minimum":0,"description":"Farming, fishing, and forestry"},"construction_extraction":{"type":"integer","minimum":0,"description":"Construction and extraction"},"installation_maintenance_repair":{"type":"integer","minimum":0,"description":"Installation, maintenance, and repair"},"production":{"type":"integer","minimum":0,"description":"Production occupations"},"transportation_material_moving":{"type":"integer","minimum":0,"description":"Transportation and material moving"},"white_collar":{"type":"integer","minimum":0,"description":"White collar occupations (aggregate)"},"blue_collar":{"type":"integer","minimum":0,"description":"Blue collar occupations (aggregate)"}},"required":["management","business_operations","computer_mathematical","architecture_engineering","life_physical_social_science","community_social_services","legal","education_training_library","arts_design_entertainment_sports_media","healthcare_practitioners_technical","healthcare_support","protective_service","food_preparation_serving","building_grounds_cleaning_maintenance","personal_care_service","sales","office_administrative_support","farming_fishing_forestry","construction_extraction","installation_maintenance_repair","production","transportation_material_moving","white_collar","blue_collar"],"description":"Current year occupation breakdown"},"forecast":{"type":"object","properties":{"management":{"type":"integer","minimum":0,"description":"Management occupations"},"business_operations":{"type":"integer","minimum":0,"description":"Business and financial operations"},"computer_mathematical":{"type":"integer","minimum":0,"description":"Computer and mathematical"},"architecture_engineering":{"type":"integer","minimum":0,"description":"Architecture and engineering"},"life_physical_social_science":{"type":"integer","minimum":0,"description":"Life, physical, and social science"},"community_social_services":{"type":"integer","minimum":0,"description":"Community and social services"},"legal":{"type":"integer","minimum":0,"description":"Legal occupations"},"education_training_library":{"type":"integer","minimum":0,"description":"Education, training, and library"},"arts_design_entertainment_sports_media":{"type":"integer","minimum":0,"description":"Arts, design, entertainment, sports, media"},"healthcare_practitioners_technical":{"type":"integer","minimum":0,"description":"Healthcare practitioners and technical"},"healthcare_support":{"type":"integer","minimum":0,"description":"Healthcare support"},"protective_service":{"type":"integer","minimum":0,"description":"Protective service"},"food_preparation_serving":{"type":"integer","minimum":0,"description":"Food preparation and serving"},"building_grounds_cleaning_maintenance":{"type":"integer","minimum":0,"description":"Building and grounds cleaning and maintenance"},"personal_care_service":{"type":"integer","minimum":0,"description":"Personal care and service"},"sales":{"type":"integer","minimum":0,"description":"Sales occupations"},"office_administrative_support":{"type":"integer","minimum":0,"description":"Office and administrative support"},"farming_fishing_forestry":{"type":"integer","minimum":0,"description":"Farming, fishing, and forestry"},"construction_extraction":{"type":"integer","minimum":0,"description":"Construction and extraction"},"installation_maintenance_repair":{"type":"integer","minimum":0,"description":"Installation, maintenance, and repair"},"production":{"type":"integer","minimum":0,"description":"Production occupations"},"transportation_material_moving":{"type":"integer","minimum":0,"description":"Transportation and material moving"},"white_collar":{"type":"integer","minimum":0,"description":"White collar occupations (aggregate)"},"blue_collar":{"type":"integer","minimum":0,"description":"Blue collar occupations (aggregate)"}},"required":["management","business_operations","computer_mathematical","architecture_engineering","life_physical_social_science","community_social_services","legal","education_training_library","arts_design_entertainment_sports_media","healthcare_practitioners_technical","healthcare_support","protective_service","food_preparation_serving","building_grounds_cleaning_maintenance","personal_care_service","sales","office_administrative_support","farming_fishing_forestry","construction_extraction","installation_maintenance_repair","production","transportation_material_moving","white_collar","blue_collar"],"description":"Five-year forecast occupation breakdown"},"nationalAvg":{"type":"object","properties":{"management":{"type":"integer","minimum":0,"description":"Management occupations"},"business_operations":{"type":"integer","minimum":0,"description":"Business and financial operations"},"computer_mathematical":{"type":"integer","minimum":0,"description":"Computer and mathematical"},"architecture_engineering":{"type":"integer","minimum":0,"description":"Architecture and engineering"},"life_physical_social_science":{"type":"integer","minimum":0,"description":"Life, physical, and social science"},"community_social_services":{"type":"integer","minimum":0,"description":"Community and social services"},"legal":{"type":"integer","minimum":0,"description":"Legal occupations"},"education_training_library":{"type":"integer","minimum":0,"description":"Education, training, and library"},"arts_design_entertainment_sports_media":{"type":"integer","minimum":0,"description":"Arts, design, entertainment, sports, media"},"healthcare_practitioners_technical":{"type":"integer","minimum":0,"description":"Healthcare practitioners and technical"},"healthcare_support":{"type":"integer","minimum":0,"description":"Healthcare support"},"protective_service":{"type":"integer","minimum":0,"description":"Protective service"},"food_preparation_serving":{"type":"integer","minimum":0,"description":"Food preparation and serving"},"building_grounds_cleaning_maintenance":{"type":"integer","minimum":0,"description":"Building and grounds cleaning and maintenance"},"personal_care_service":{"type":"integer","minimum":0,"description":"Personal care and service"},"sales":{"type":"integer","minimum":0,"description":"Sales occupations"},"office_administrative_support":{"type":"integer","minimum":0,"description":"Office and administrative support"},"farming_fishing_forestry":{"type":"integer","minimum":0,"description":"Farming, fishing, and forestry"},"construction_extraction":{"type":"integer","minimum":0,"description":"Construction and extraction"},"installation_maintenance_repair":{"type":"integer","minimum":0,"description":"Installation, maintenance, and repair"},"production":{"type":"integer","minimum":0,"description":"Production occupations"},"transportation_material_moving":{"type":"integer","minimum":0,"description":"Transportation and material moving"},"white_collar":{"type":"integer","minimum":0,"description":"White collar occupations (aggregate)"},"blue_collar":{"type":"integer","minimum":0,"description":"Blue collar occupations (aggregate)"}},"required":["management","business_operations","computer_mathematical","architecture_engineering","life_physical_social_science","community_social_services","legal","education_training_library","arts_design_entertainment_sports_media","healthcare_practitioners_technical","healthcare_support","protective_service","food_preparation_serving","building_grounds_cleaning_maintenance","personal_care_service","sales","office_administrative_support","farming_fishing_forestry","construction_extraction","installation_maintenance_repair","production","transportation_material_moving","white_collar","blue_collar"],"description":"National average occupation breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"management":5000,"sales":3000},"forecast":{"management":5000,"sales":3000},"nationalAvg":{"management":155,"sales":110}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}},"/area/demographics/population-by-industry":{"post":{"tags":["area","demographics"],"description":"Get population-by-industry demographics (current and forecast) for a geographic area. Supports multiple area input types including polygons, radius, administrative boundaries, and H3 indexes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}},"required":["type","coordinates"],"description":"A GeoJSON Polygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2}}}}},"required":["type","coordinates"],"description":"A GeoJSON MultiPolygon geometry"},{"type":"object","properties":{"type":{"type":"string","enum":["radius"]},"center":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[longitude, latitude]"},"radius":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Radius distance"},"unit":{"type":"string","enum":["miles","meters"],"description":"Unit of measurement for radius"}},"required":["type","center","radius","unit"],"description":"A circular area defined by center point and radius"},{"type":"object","properties":{"type":{"type":"string","enum":["administrative"]},"boundary":{"type":"string","enum":["state","zipcode","city","county","cbg","cb"],"description":"Type of administrative boundary"},"id":{"type":"string","description":"Administrative boundary identifier"}},"required":["type","boundary","id"],"description":"A predefined administrative boundary (state, city, ZIP code, etc.)"},{"type":"object","properties":{"type":{"type":"string","enum":["h3"]},"index":{"type":"string","pattern":"^[0-9a-f]{15}$/i","description":"H3 hexagon index"}},"required":["type","index"],"description":"A Uber H3 hexagonal grid cell"}]}},"required":["area"]},"example":{"area":{"type":"radius","center":[-97.688939,30.217942],"radius":1,"unit":"miles"}}}}},"responses":{"200":{"description":"Retrieves employment by industry sector breakdown for an area using H3 demographics data","content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"object","properties":{"agriculture_forestry_fishing_hunting_mining":{"type":"integer","minimum":0,"description":"Agriculture, forestry, fishing, hunting, mining"},"construction":{"type":"integer","minimum":0,"description":"Construction"},"manufacturing":{"type":"integer","minimum":0,"description":"Manufacturing"},"wholesale_trade":{"type":"integer","minimum":0,"description":"Wholesale trade"},"retail_trade":{"type":"integer","minimum":0,"description":"Retail trade"},"transportation_utilities":{"type":"integer","minimum":0,"description":"Transportation and utilities"},"information":{"type":"integer","minimum":0,"description":"Information"},"finance_insurance_real_estate":{"type":"integer","minimum":0,"description":"Finance, insurance, real estate"},"professional_scientific_management_admin":{"type":"integer","minimum":0,"description":"Professional, scientific, management, admin"},"education":{"type":"integer","minimum":0,"description":"Education services"},"healthcare":{"type":"integer","minimum":0,"description":"Healthcare and social assistance"},"arts_entertainment_recreation_accommodation_food":{"type":"integer","minimum":0,"description":"Arts, entertainment, recreation, accommodation, food"},"other_services":{"type":"integer","minimum":0,"description":"Other services (except public admin)"},"public_administration":{"type":"integer","minimum":0,"description":"Public administration"}},"required":["agriculture_forestry_fishing_hunting_mining","construction","manufacturing","wholesale_trade","retail_trade","transportation_utilities","information","finance_insurance_real_estate","professional_scientific_management_admin","education","healthcare","arts_entertainment_recreation_accommodation_food","other_services","public_administration"],"description":"Current year industry breakdown"},"forecast":{"type":"object","properties":{"agriculture_forestry_fishing_hunting_mining":{"type":"integer","minimum":0,"description":"Agriculture, forestry, fishing, hunting, mining"},"construction":{"type":"integer","minimum":0,"description":"Construction"},"manufacturing":{"type":"integer","minimum":0,"description":"Manufacturing"},"wholesale_trade":{"type":"integer","minimum":0,"description":"Wholesale trade"},"retail_trade":{"type":"integer","minimum":0,"description":"Retail trade"},"transportation_utilities":{"type":"integer","minimum":0,"description":"Transportation and utilities"},"information":{"type":"integer","minimum":0,"description":"Information"},"finance_insurance_real_estate":{"type":"integer","minimum":0,"description":"Finance, insurance, real estate"},"professional_scientific_management_admin":{"type":"integer","minimum":0,"description":"Professional, scientific, management, admin"},"education":{"type":"integer","minimum":0,"description":"Education services"},"healthcare":{"type":"integer","minimum":0,"description":"Healthcare and social assistance"},"arts_entertainment_recreation_accommodation_food":{"type":"integer","minimum":0,"description":"Arts, entertainment, recreation, accommodation, food"},"other_services":{"type":"integer","minimum":0,"description":"Other services (except public admin)"},"public_administration":{"type":"integer","minimum":0,"description":"Public administration"}},"required":["agriculture_forestry_fishing_hunting_mining","construction","manufacturing","wholesale_trade","retail_trade","transportation_utilities","information","finance_insurance_real_estate","professional_scientific_management_admin","education","healthcare","arts_entertainment_recreation_accommodation_food","other_services","public_administration"],"description":"Five-year forecast industry breakdown"},"nationalAvg":{"type":"object","properties":{"agriculture_forestry_fishing_hunting_mining":{"type":"integer","minimum":0,"description":"Agriculture, forestry, fishing, hunting, mining"},"construction":{"type":"integer","minimum":0,"description":"Construction"},"manufacturing":{"type":"integer","minimum":0,"description":"Manufacturing"},"wholesale_trade":{"type":"integer","minimum":0,"description":"Wholesale trade"},"retail_trade":{"type":"integer","minimum":0,"description":"Retail trade"},"transportation_utilities":{"type":"integer","minimum":0,"description":"Transportation and utilities"},"information":{"type":"integer","minimum":0,"description":"Information"},"finance_insurance_real_estate":{"type":"integer","minimum":0,"description":"Finance, insurance, real estate"},"professional_scientific_management_admin":{"type":"integer","minimum":0,"description":"Professional, scientific, management, admin"},"education":{"type":"integer","minimum":0,"description":"Education services"},"healthcare":{"type":"integer","minimum":0,"description":"Healthcare and social assistance"},"arts_entertainment_recreation_accommodation_food":{"type":"integer","minimum":0,"description":"Arts, entertainment, recreation, accommodation, food"},"other_services":{"type":"integer","minimum":0,"description":"Other services (except public admin)"},"public_administration":{"type":"integer","minimum":0,"description":"Public administration"}},"required":["agriculture_forestry_fishing_hunting_mining","construction","manufacturing","wholesale_trade","retail_trade","transportation_utilities","information","finance_insurance_real_estate","professional_scientific_management_admin","education","healthcare","arts_entertainment_recreation_accommodation_food","other_services","public_administration"],"description":"National average industry breakdown"}},"required":["current","forecast","nationalAvg"]},"example":{"current":{"retail_trade":4000,"healthcare":3500},"forecast":{"retail_trade":4000,"healthcare":3500},"nationalAvg":{"retail_trade":130,"healthcare":145}}}}},"400":{"description":"Invalid area input","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"Invalid area geometry","code":"INVALID_AREA"}}}},"404":{"description":"No demographic data found","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["AlphaMapError"]},"message":{"type":"string"},"code":{"anyOf":[{"type":"string","enum":["NOT_FOUND"]},{"type":"string","enum":["BRAND_NOT_FOUND"]},{"type":"string","enum":["LOCATION_NOT_FOUND"]},{"type":"string","enum":["BOUNDARY_NOT_FOUND"]},{"type":"string","enum":["INVALID_REQUEST"]},{"type":"string","enum":["INVALID_AREA"]},{"type":"string","enum":["INVALID_H3_INDEX"]},{"type":"string","enum":["SEARCH_ERROR"]},{"type":"string","enum":["ALREADY_EXISTS"]},{"type":"string","enum":["R2_FETCH_ERROR"]},{"type":"string","enum":["R2_DECOMPRESS_ERROR"]},{"type":"string","enum":["R2_READ_ERROR"]},{"type":"string","enum":["R2_PARSE_ERROR"]}]}},"required":["_tag","message","code"]},"example":{"_tag":"AlphaMapError","message":"No demographic data found for the specified area","code":"NOT_FOUND"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["ValidationError"]},"message":{"type":"string"},"details":{"type":"string"}},"required":["_tag","message","details"]},"example":{"_tag":"ValidationError","message":"Invalid input parameters","issues":[{"path":["area","radius"],"message":"Radius must be a positive number"}]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"_tag":{"type":"string","enum":["InternalServerError"]},"message":{"type":"string"}},"required":["_tag","message"]},"example":{"_tag":"InternalServerError","message":"An unexpected error occurred while processing your request"}}}}}}}}}