{"openapi":"3.0.3","info":{"title":"Pirate Map Public API","version":"1.0.0","description":"GeoAI-native real estate data API. Access parcel data, lead scoring, demographics, and zoning information across 31 counties in North Carolina and South Carolina.","contact":{"name":"Pirate Map API Support"}},"servers":[{"url":"/api/v1","description":"Production API"}],"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key passed via the X-API-Key header"},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"API key passed as a query parameter"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"Meta":{"type":"object","properties":{"tier":{"type":"string","description":"API key tier"},"response_time_ms":{"type":"integer","description":"Response time in milliseconds"}}},"OverlayFeature":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"geometry":{"type":"object","description":"GeoJSON geometry (mixed types: Point, Polygon, MultiPolygon, LineString)"},"properties":{"type":"object","properties":{"id":{"type":"integer"},"layer_type":{"type":"string"},"name":{"type":"string","nullable":true}},"additionalProperties":true,"description":"Overlay attributes vary by layer_type"}}},"OverlayCollection":{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"$ref":"#/components/schemas/OverlayFeature"}},"meta":{"$ref":"#/components/schemas/Meta"}}},"FloodZoneResult":{"type":"object","properties":{"flood_zone":{"type":"string","nullable":true,"description":"FEMA flood zone designation"},"flood_zone_subtype":{"type":"string","nullable":true},"in_floodplain":{"type":"boolean"},"lat":{"type":"number"},"lng":{"type":"number"},"meta":{"$ref":"#/components/schemas/Meta"}}},"ElevationResult":{"type":"object","properties":{"elevation_ft":{"type":"number","nullable":true,"description":"Elevation in feet"},"elevation_m":{"type":"number","nullable":true,"description":"Elevation in meters"},"lat":{"type":"number"},"lng":{"type":"number"},"meta":{"$ref":"#/components/schemas/Meta"}}},"ValuationResult":{"type":"object","properties":{"parcel_id":{"type":"string"},"county":{"type":"string"},"action":{"type":"string","enum":["comps","estimate"]},"data":{"type":"object","description":"Valuation data (comps list or estimate breakdown)"},"meta":{"$ref":"#/components/schemas/Meta"}}},"ParcelFeature":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"geometry":{"type":"object","description":"GeoJSON geometry (MultiPolygon). Detail depends on tier."},"properties":{"type":"object","properties":{"parcel_id":{"type":"string"},"county":{"type":"string"},"state":{"type":"string"},"site_address":{"type":"string","nullable":true},"gis_acres":{"type":"number","nullable":true},"zoning_code":{"type":"string","nullable":true},"owner_name":{"type":"string","nullable":true,"description":"Basic tier+"},"total_value":{"type":"number","nullable":true,"description":"Basic tier+"},"land_value":{"type":"number","nullable":true,"description":"Basic tier+"},"building_value":{"type":"number","nullable":true,"description":"Basic tier+"},"land_use":{"type":"string","nullable":true,"description":"Pro tier+"},"owner_type":{"type":"string","nullable":true,"description":"Pro tier+"},"lead_score":{"type":"integer","nullable":true,"description":"Pro tier+"}}}}},"ParcelCollection":{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"$ref":"#/components/schemas/ParcelFeature"}},"meta":{"$ref":"#/components/schemas/Meta"}}},"ScoreResult":{"type":"object","properties":{"parcel_id":{"type":"string"},"county":{"type":"string"},"score":{"type":"integer","description":"Lead score 0-100"},"grade":{"type":"string","enum":["A","B","C","D","F"]},"breakdown":{"type":"object","properties":{"vacancy":{"type":"object","properties":{"score":{"type":"integer"},"max":{"type":"integer"}}},"size":{"type":"object","properties":{"score":{"type":"integer"},"max":{"type":"integer"}}},"value":{"type":"object","properties":{"score":{"type":"integer"},"max":{"type":"integer"}}},"owner":{"type":"object","properties":{"score":{"type":"integer"},"max":{"type":"integer"}}},"market":{"type":"object","properties":{"score":{"type":"integer"},"max":{"type":"integer"}}}}},"factors":{"type":"array","items":{"type":"string"},"description":"Human-readable scoring factors"},"context":{"type":"string","description":"residential, commercial, or unknown"},"zoning_code":{"type":"string","nullable":true},"proposed_use":{"type":"string","nullable":true},"meta":{"$ref":"#/components/schemas/Meta"}}},"DemographicsResult":{"type":"object","properties":{"demographics":{"type":"object","nullable":true,"properties":{"block_group":{"type":"string"},"geoid":{"type":"string"},"total_population":{"type":"integer","nullable":true},"median_age":{"type":"integer","nullable":true},"median_household_income":{"type":"integer","nullable":true},"per_capita_income":{"type":"integer","nullable":true},"total_households":{"type":"integer","nullable":true},"median_home_value":{"type":"integer","nullable":true},"homeownership_rate":{"type":"number","nullable":true},"education":{"type":"object","nullable":true},"employment":{"type":"object","nullable":true},"income_distribution":{"type":"object","nullable":true}}},"lat":{"type":"number"},"lng":{"type":"number"},"meta":{"$ref":"#/components/schemas/Meta"}}},"ZoningResult":{"type":"object","properties":{"parcel_id":{"type":"string"},"county":{"type":"string"},"state":{"type":"string"},"zoning_code":{"type":"string","nullable":true},"land_use":{"type":"string","nullable":true},"land_use_code":{"type":"string","nullable":true},"allowed_uses":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"by_right":{"type":"array","items":{"type":"string"}},"conditional":{"type":"array","items":{"type":"string"}},"not_permitted":{"type":"array","items":{"type":"string"}},"notes":{"type":"string","nullable":true}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}},"paths":{"/parcels":{"get":{"summary":"Query parcels","description":"Retrieve parcel data by bounding box or parcel ID. Fields returned depend on your API tier. All tiers: parcel_id, county, state, address, acres, zoning_code, simplified geometry. Basic+: owner, values. Pro+: all fields, full geometry.","tags":["Parcels"],"parameters":[{"name":"parcel_id","in":"query","description":"Parcel ID (use with county)","schema":{"type":"string"}},{"name":"county","in":"query","description":"County name (e.g. Mecklenburg, Wake, York)","schema":{"type":"string"}},{"name":"bbox","in":"query","description":"Bounding box: sw_lng,ne_lng,sw_lat,ne_lat","schema":{"type":"string"},"example":"-80.9,-80.8,35.2,35.3"},{"name":"limit","in":"query","description":"Max results (default 100, max 1000)","schema":{"type":"integer","default":100,"maximum":1000}}],"responses":{"200":{"description":"GeoJSON FeatureCollection of parcels","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParcelCollection"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key"},"429":{"description":"Rate limit exceeded"}}}},"/parcels/score":{"post":{"summary":"Score a parcel","description":"Compute a development lead score (0-100) for a parcel. Pro tier required. Score components: vacancy (0-25), size (0-15), value opportunity (0-20), owner motivation (0-20), market (0-20).","tags":["Scoring"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["parcel_id","county"],"properties":{"parcel_id":{"type":"string","description":"Parcel ID"},"county":{"type":"string","description":"County name"},"proposed_use":{"type":"string","description":"Optional proposed development use for context"}}}}}},"responses":{"200":{"description":"Lead score result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreResult"}}}},"403":{"description":"Tier too low (Pro required)"},"404":{"description":"Parcel not found"}}}},"/demographics":{"get":{"summary":"Get demographics for a location","description":"Returns Census ACS 5-Year demographic data for the block group at the given coordinates. Includes population, income, education, employment, and housing data. Basic tier required.","tags":["Demographics"],"parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude","schema":{"type":"number"},"example":35.22},{"name":"lng","in":"query","required":true,"description":"Longitude","schema":{"type":"number"},"example":-80.84}],"responses":{"200":{"description":"Demographics data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemographicsResult"}}}},"403":{"description":"Tier too low (Basic required)"}}}},"/zoning":{"get":{"summary":"Get zoning for a parcel","description":"Returns the zoning code and allowed uses for a parcel. Includes by-right, conditional, and not-permitted use lists based on standard NC/SC zoning patterns. Basic tier required.","tags":["Zoning"],"parameters":[{"name":"parcel_id","in":"query","required":true,"description":"Parcel ID","schema":{"type":"string"}},{"name":"county","in":"query","required":true,"description":"County name","schema":{"type":"string"}}],"responses":{"200":{"description":"Zoning and allowed uses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZoningResult"}}}},"403":{"description":"Tier too low (Basic required)"},"404":{"description":"Parcel not found"}}}},"/overlays":{"get":{"summary":"Query overlay layers","description":"Retrieve overlay features (flood zones, schools, fire stations, parks, utilities, etc.) within a bounding box. Optionally filter by layer_type. Free tier included.","tags":["Overlays"],"parameters":[{"name":"bbox","in":"query","required":true,"description":"Bounding box: sw_lng,sw_lat,ne_lng,ne_lat","schema":{"type":"string"},"example":"-80.9,35.1,-80.8,35.3"},{"name":"layer_type","in":"query","description":"Filter by overlay type (e.g. flood_zone, school, fire_station, park, water_line, sewer_line)","schema":{"type":"string"}}],"responses":{"200":{"description":"GeoJSON FeatureCollection of overlay features","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverlayCollection"}}}},"400":{"description":"Missing or invalid bbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key"},"429":{"description":"Rate limit exceeded"}}}},"/flood-zone":{"get":{"summary":"Flood zone lookup","description":"Returns FEMA flood zone designation for a given coordinate. Basic tier required.","tags":["Environmental"],"parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude","schema":{"type":"number"},"example":35.22},{"name":"lng","in":"query","required":true,"description":"Longitude","schema":{"type":"number"},"example":-80.84}],"responses":{"200":{"description":"Flood zone result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FloodZoneResult"}}}},"400":{"description":"Missing or invalid coordinates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key"},"403":{"description":"Tier too low (Basic required)"},"429":{"description":"Rate limit exceeded"}}}},"/elevation":{"get":{"summary":"Elevation lookup","description":"Returns ground elevation in feet and meters for a given coordinate. Basic tier required.","tags":["Environmental"],"parameters":[{"name":"lat","in":"query","required":true,"description":"Latitude","schema":{"type":"number"},"example":35.22},{"name":"lng","in":"query","required":true,"description":"Longitude","schema":{"type":"number"},"example":-80.84}],"responses":{"200":{"description":"Elevation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ElevationResult"}}}},"400":{"description":"Missing or invalid coordinates","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key"},"403":{"description":"Tier too low (Basic required)"},"429":{"description":"Rate limit exceeded"}}}},"/valuation":{"get":{"summary":"Parcel valuation","description":"Get comparable sales or automated valuation estimate for a parcel. Pro tier required.","tags":["Valuation"],"parameters":[{"name":"parcel_id","in":"query","required":true,"description":"Parcel ID","schema":{"type":"string"}},{"name":"county","in":"query","required":true,"description":"County name","schema":{"type":"string"}},{"name":"action","in":"query","required":true,"description":"Action: \"comps\" for comparable sales, \"estimate\" for automated valuation","schema":{"type":"string","enum":["comps","estimate"]}}],"responses":{"200":{"description":"Valuation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValuationResult"}}}},"400":{"description":"Missing or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Invalid or missing API key"},"403":{"description":"Tier too low (Pro required)"},"429":{"description":"Rate limit exceeded"}}}}},"x-tier-info":{"free":{"rate_limit":"10/min, 100/day","endpoints":["/parcels","/overlays","/docs"],"fields":"Basic parcel info + simplified geometry + overlay layers"},"basic":{"rate_limit":"60/min, 5,000/day","endpoints":["/parcels","/demographics","/zoning","/overlays","/flood-zone","/elevation","/docs"],"fields":"Full parcel info + owner + values + environmental data"},"pro":{"rate_limit":"300/min, 50,000/day","endpoints":["/parcels","/parcels/score","/demographics","/zoning","/overlays","/flood-zone","/elevation","/valuation","/docs"],"fields":"All fields + full geometry + lead scoring + valuation"},"enterprise":{"rate_limit":"1,000/min, unlimited/day","endpoints":"All endpoints","fields":"All fields + full geometry + custom integrations"}}}