openapi: 3.1.0 info: title: WildfireService API version: 1.0.0 paths: /api/wildfire/v1/list-fire-detections: get: tags: - WildfireService summary: ListFireDetections description: ListFireDetections retrieves satellite-detected active fires from NASA FIRMS. operationId: ListFireDetections parameters: - name: start in: query description: Start of time range (inclusive), Unix epoch milliseconds. required: false schema: type: string format: int64 - name: end in: query description: End of time range (inclusive), Unix epoch milliseconds. required: false schema: type: string format: int64 - name: page_size in: query description: Maximum items per page (1-100). required: false schema: type: integer format: int32 - name: cursor in: query description: Cursor for next page. required: false schema: type: string - name: ne_lat in: query description: North-east latitude of bounding box. required: false schema: type: number format: double - name: ne_lon in: query description: North-east longitude of bounding box. required: false schema: type: number format: double - name: sw_lat in: query description: South-west latitude of bounding box. required: false schema: type: number format: double - name: sw_lon in: query description: South-west longitude of bounding box. required: false schema: type: number format: double responses: "200": description: Successful response content: application/json: schema: $ref: '#/components/schemas/ListFireDetectionsResponse' "400": description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' default: description: Error response content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: message: type: string description: Error message (e.g., 'user not found', 'database connection failed') description: Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize. FieldViolation: type: object properties: field: type: string description: The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key') description: type: string description: Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing') required: - field - description description: FieldViolation describes a single validation error for a specific field. ValidationError: type: object properties: violations: type: array items: $ref: '#/components/schemas/FieldViolation' description: List of validation violations required: - violations description: ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong. ListFireDetectionsRequest: type: object properties: start: type: integer format: int64 description: 'Start of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' end: type: integer format: int64 description: 'End of time range (inclusive), Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' pageSize: type: integer format: int32 description: Maximum items per page (1-100). cursor: type: string description: Cursor for next page. neLat: type: number format: double description: North-east latitude of bounding box. neLon: type: number format: double description: North-east longitude of bounding box. swLat: type: number format: double description: South-west latitude of bounding box. swLon: type: number format: double description: South-west longitude of bounding box. description: ListFireDetectionsRequest specifies filters for retrieving fire detections from NASA FIRMS. ListFireDetectionsResponse: type: object properties: fireDetections: type: array items: $ref: '#/components/schemas/FireDetection' pagination: $ref: '#/components/schemas/PaginationResponse' description: ListFireDetectionsResponse contains the list of fire detections matching the request filters. FireDetection: type: object properties: id: type: string maxLength: 100 minLength: 1 description: Unique detection identifier. location: $ref: '#/components/schemas/GeoCoordinates' brightness: type: number format: double description: Brightness temperature in Kelvin. frp: type: number format: double description: Fire radiative power in MW. confidence: type: string enum: - FIRE_CONFIDENCE_UNSPECIFIED - FIRE_CONFIDENCE_LOW - FIRE_CONFIDENCE_NOMINAL - FIRE_CONFIDENCE_HIGH description: FireConfidence represents the confidence level of a fire detection. satellite: type: string description: Satellite that detected the fire (e.g., "MODIS", "VIIRS", "LANDSAT"). detectedAt: type: integer format: int64 description: 'Time the fire was detected, as Unix epoch milliseconds.. Warning: Values > 2^53 may lose precision in JavaScript' region: type: string description: Monitored region name (e.g., "Ukraine", "Russia", "Iran"). dayNight: type: string description: Day or night detection ("D" or "N"). required: - id description: FireDetection represents a satellite-detected active fire from NASA FIRMS. GeoCoordinates: type: object properties: latitude: type: number maximum: 90 minimum: -90 format: double description: Latitude in decimal degrees (-90 to 90). longitude: type: number maximum: 180 minimum: -180 format: double description: Longitude in decimal degrees (-180 to 180). description: GeoCoordinates represents a geographic location using WGS84 coordinates. PaginationResponse: type: object properties: nextCursor: type: string description: Cursor for fetching the next page. Empty string indicates no more pages. totalCount: type: integer format: int32 description: Total count of items matching the query, if known. Zero if the total is unknown. description: PaginationResponse contains pagination metadata returned alongside list results.