{"openapi": "3.1.0", "info": {"title": "QuakeFYI API", "version": "1.0.0", "description": "Real-time earthquake data, seismic risk assessments, and global statistics. Powered by USGS and NOAA data. No authentication required.", "contact": {"name": "QuakeFYI", "url": "https://quakefyi.com/developers/"}}, "servers": [{"url": "https://quakefyi.com", "description": "Production"}], "paths": {"/api/recent/": {"get": {"operationId": "getRecentEarthquakes", "summary": "Recent earthquakes", "description": "Returns recent earthquakes with optional magnitude and limit filtering.", "parameters": [{"name": "limit", "in": "query", "schema": {"type": "integer", "default": 50, "maximum": 200}, "description": "Maximum number of results."}, {"name": "min_magnitude", "in": "query", "schema": {"type": "number", "default": 2.5}, "description": "Minimum magnitude filter."}], "responses": {"200": {"description": "Array of earthquake objects.", "content": {"application/json": {"schema": {"type": "object", "properties": {"earthquakes": {"type": "array", "items": {"$ref": "#/components/schemas/Earthquake"}}}}}}}}, "tags": ["Earthquakes"]}}, "/api/search/": {"get": {"operationId": "searchEarthquakes", "summary": "Search earthquakes by place name", "parameters": [{"name": "q", "in": "query", "required": true, "schema": {"type": "string", "minLength": 2}, "description": "Search term (place name)."}], "responses": {"200": {"description": "Search results.", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/EarthquakeSearchResult"}}}}}}}}, "tags": ["Earthquakes"]}}, "/api/live-feed/": {"get": {"operationId": "getLiveFeed", "summary": "Live earthquake GeoJSON feed", "description": "GeoJSON FeatureCollection for map rendering. Auto-refreshes every 30s on the map page.", "parameters": [{"name": "hours", "in": "query", "schema": {"type": "integer", "enum": [1, 6, 24, 168], "default": 24}, "description": "Time window in hours."}], "responses": {"200": {"description": "GeoJSON FeatureCollection.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GeoJSON"}}}}}, "tags": ["Earthquakes"]}}, "/api/plate-boundaries/": {"get": {"operationId": "getPlateBoundaries", "summary": "Tectonic plate boundaries (GeoJSON)", "description": "GeoJSON of tectonic plate boundaries for map overlays.", "responses": {"200": {"description": "GeoJSON FeatureCollection of plate boundaries.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GeoJSON"}}}}}, "tags": ["Reference"]}}, "/api/v1/earthquakes/": {"get": {"operationId": "v1ListEarthquakes", "summary": "Paginated earthquake list", "description": "Paginated, filtered earthquake list with magnitude, time, and country filtering.", "parameters": [{"name": "min_mag", "in": "query", "schema": {"type": "number", "default": 0}, "description": "Minimum magnitude."}, {"name": "max_mag", "in": "query", "schema": {"type": "number", "default": 10}, "description": "Maximum magnitude."}, {"name": "hours", "in": "query", "schema": {"type": "integer", "default": 24, "maximum": 720}, "description": "Time window in hours (max 30 days)."}, {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 100, "maximum": 500}, "description": "Results per page."}, {"name": "offset", "in": "query", "schema": {"type": "integer", "default": 0}, "description": "Pagination offset."}, {"name": "country", "in": "query", "schema": {"type": "string"}, "description": "ISO 3166-1 alpha-2 country code (e.g., JP)."}], "responses": {"200": {"description": "Paginated earthquake list.", "content": {"application/json": {"schema": {"type": "object", "properties": {"count": {"type": "integer"}, "earthquakes": {"type": "array", "items": {"$ref": "#/components/schemas/Earthquake"}}}}}}}}, "tags": ["API v1"]}}, "/api/v1/countries/{iso2}/risk/": {"get": {"operationId": "v1CountryRisk", "summary": "Country seismic risk assessment", "parameters": [{"name": "iso2", "in": "path", "required": true, "schema": {"type": "string", "pattern": "^[A-Z]{2}$"}, "description": "ISO 3166-1 alpha-2 code.", "example": "JP"}], "responses": {"200": {"description": "Country risk profile.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CountryRisk"}}}}, "404": {"description": "Country not found."}}, "tags": ["API v1"]}}, "/api/v1/stats/": {"get": {"operationId": "v1GlobalStats", "summary": "Global earthquake statistics", "description": "24-hour and 7-day earthquake counts, including significant and major event breakdowns.", "responses": {"200": {"description": "Global statistics.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GlobalStats"}}}}}, "tags": ["API v1"]}}}, "components": {"schemas": {"Earthquake": {"type": "object", "properties": {"event_id": {"type": "string", "example": "us7000test"}, "magnitude": {"type": "number", "example": 5.2}, "depth_km": {"type": "number", "example": 10.0}, "latitude": {"type": "number", "example": 35.68}, "longitude": {"type": "number", "example": 139.69}, "place_description": {"type": "string", "example": "25km NW of Tokyo, Japan"}, "occurred_at": {"type": "string", "format": "date-time"}, "alert_level": {"type": "string", "nullable": true, "enum": ["green", "yellow", "orange", "red", null]}, "tsunami_flag": {"type": "boolean"}}}, "EarthquakeSearchResult": {"type": "object", "properties": {"event_id": {"type": "string"}, "magnitude": {"type": "number"}, "place_description": {"type": "string"}, "occurred_at": {"type": "string", "format": "date-time"}, "slug": {"type": "string"}}}, "GeoJSON": {"type": "object", "properties": {"type": {"type": "string", "enum": ["FeatureCollection"]}, "features": {"type": "array", "items": {"type": "object"}}}}, "CountryRisk": {"type": "object", "properties": {"country": {"type": "object", "properties": {"name": {"type": "string", "example": "Japan"}, "iso2": {"type": "string", "example": "JP"}, "seismic_zone": {"type": "string", "enum": ["very_high", "high", "moderate", "low", "minimal"]}, "continent": {"type": "string"}, "total_earthquakes": {"type": "integer"}, "total_significant": {"type": "integer"}, "largest_magnitude": {"type": "number", "nullable": true}}}, "recent_30d": {"type": "integer", "description": "Earthquakes in last 30 days."}}}, "GlobalStats": {"type": "object", "properties": {"last_24h": {"type": "object", "properties": {"total": {"type": "integer"}, "significant": {"type": "integer"}, "major": {"type": "integer"}}}, "last_7d": {"type": "object", "properties": {"total": {"type": "integer"}, "significant": {"type": "integer"}, "major": {"type": "integer"}}}, "countries_count": {"type": "integer"}, "historical_count": {"type": "integer"}}}}}, "tags": [{"name": "Earthquakes", "description": "Real-time earthquake data from USGS."}, {"name": "Reference", "description": "Tectonic plates, fault lines, and other reference data."}, {"name": "API v1", "description": "Versioned REST API with pagination and filtering."}]}