Skip to content

Latest commit

 

History

History
404 lines (315 loc) · 7.9 KB

API.md

File metadata and controls

404 lines (315 loc) · 7.9 KB

WeatherTrack Pro - API Documentation

Base URL

  • Original version: http://localhost:3000
  • Optimized version: http://localhost:3001

Endpoints

1. Check API health status

Available only on the optimized version (new API)

This endpoint allows checking the API health status and obtaining statistics on the database and cache.

Method: GET

URL: /weather/health

Example:

GET /weather/health

Success response:

  • Code: 200 OK
  • Body:
{
  "status": "healthy",
  "timestamp": "2025-11-17T16:00:00.000Z",
  "database": {
    "status": "connected",
    "totalRecords": 50000,
    "locations": 20,
    "dateRange": {
      "min": "2023-11-17T00:00:00.000Z",
      "max": "2025-11-17T00:00:00.000Z"
    }
  },
  "cache": {
    "hits": 1250,
    "misses": 350,
    "hitRate": 78.125,
    "size": 45,
    "maxSize": 100,
    "ttl": 60000
  }
}

Error response:

  • Code: 503 Service Unavailable
  • Body:
{
  "status": "unhealthy",
  "timestamp": "2025-11-17T16:00:00.000Z",
  "error": "Database connection failed"
}

Recommended usage:

  • Application monitoring
  • Database connectivity verification
  • Cache performance monitoring
  • Integration into CI/CD pipelines

2. Add weather data

Method: POST

URL: /weather/data

Headers:

Content-Type: application/json

Body:

{
  "location": "Lyon",
  "date": "2023-12-24T23:00:00.000Z",
  "temperature": 25,
  "humidity": 40
}

Success response:

  • Code: 200 OK

Error response:

  • Code: 500 Internal Server Error

3. Retrieve weather data by location

Method: GET

URL: /weather/data/:location

URL parameters:

  • location (string, required): Location name

Query parameters:

  • from (Date, optional): Start date (ISO 8601 format)
  • to (Date, optional): End date (ISO 8601 format)
  • limit (number, optional): Maximum number of results (default: 1000, max: 10000) [NEW API ONLY]
  • offset (number, optional): Offset for pagination (default: 0) [NEW API ONLY]

Examples:

# Default behavior (compatible with old API)
GET /weather/data/Lyon

# With date filtering
GET /weather/data/Lyon?from=2023-12-22&to=2023-12-25

# With pagination (NEW API ONLY) - first 100 results
GET /weather/data/Lyon?limit=100&offset=0

# With pagination (NEW API ONLY) - Page 2 (results 100-199)
GET /weather/data/Lyon?limit=100&offset=100

# Combining filtering + pagination (NEW API ONLY)
GET /weather/data/Lyon?from=2023-01-01&to=2023-12-31&limit=500&offset=1000

Success response:

  • Code: 200 OK
  • Body:
[
  {
    "location": "Lyon",
    "date": "2023-12-22T23:00:00.000Z",
    "temperature": 27,
    "humidity": 40
  },
  {
    "location": "Lyon",
    "date": "2023-12-24T23:00:00.000Z",
    "temperature": 25,
    "humidity": 40
  }
]

Response if no data:

  • Code: 200 OK
  • Body: null

Error response:

  • Code: 500 Internal Server Error

Notes on pagination (NEW API):

  • Without limit and offset parameters, the API returns the first 1000 results (default behavior)
  • Pagination significantly improves performance with large volumes (99%+ on 50k records)
  • The limit parameter accepts values from 1 to 10000
  • The offset parameter allows "skipping" results for pagination

Pagination use cases:

  • limit=50: For paginated display in a user interface
  • limit=100&offset=0 then limit=100&offset=100: For infinite scroll
  • limit=5000: For data exports in multiple passes
  • limit=1: To quickly check for data existence

4. Calculate average temperature

Method: GET

URL: /weather/avg/:location

URL parameters:

  • location (string, required): Location name

Query parameters:

  • from (Date, optional): Start date (ISO 8601 format)
  • to (Date, optional): End date (ISO 8601 format)

Example:

GET /weather/avg/Lyon?from=2023-12-22&to=2023-12-25

Success response:

  • Code: 200 OK
  • Body:
{
  "avg": 24.166666666666668
}

Response if no data:

  • Code: 200 OK
  • Body:
{
  "avg": null
}

Error response:

  • Code: 500 Internal Server Error

5. Retrieve maximum temperature

Method: GET

URL: /weather/max/:location

URL parameters:

  • location (string, required): Location name

Query parameters:

  • from (Date, optional): Start date (ISO 8601 format)
  • to (Date, optional): End date (ISO 8601 format)

Example:

GET /weather/max/Lyon?from=2023-12-22

Success response:

  • Code: 200 OK
  • Body:
{
  "max": 27
}

Response if no data:

  • Code: 200 OK
  • Body:
{
  "max": null
}

Error response:

  • Code: 500 Internal Server Error

6. Retrieve minimum temperature

Method: GET

URL: /weather/min/:location

URL parameters:

  • location (string, required): Location name

Query parameters:

  • from (Date, optional): Start date (ISO 8601 format)
  • to (Date, optional): End date (ISO 8601 format)

Example:

GET /weather/min/Lyon?to=2023-12-25

Success response:

  • Code: 200 OK
  • Body:
{
  "min": 23
}

Response if no data:

  • Code: 200 OK
  • Body:
{
  "min": null
}

Error response:

  • Code: 500 Internal Server Error

Data formats

WeatherData

{
  location: string,
  date: Date,
  temperature: number,
  humidity: number
}

WeatherFilter (OLD API)

{
  from?: Date,
  to?: Date
}

WeatherFilter (NEW API)

{
  from?: Date,
  to?: Date,
  limit?: number,    // Default: 1000, Min: 1, Max: 10000
  offset?: number    // Default: 0, Min: 0
}

HTTP status codes

  • 200 OK: Request successful
  • 404 Not Found: Route not found
  • 500 Internal Server Error: Server error
  • 503 Service Unavailable: Service unavailable (/health endpoint only)

Differences between versions

Old API (localhost:3000)

  • No /weather/health endpoint
  • No pagination support on /weather/data/:location
  • Returns up to all available data for a location

New API (localhost:3001)

  • /weather/health endpoint for monitoring
  • Pagination support with limit and offset
  • Optimized performance (95-99% faster)
  • In-memory cache for frequent queries
  • Database indexes for ultra-fast queries
  • 100% backward compatible with old API

Important notes

Date format

  • All dates must be in ISO 8601 format
  • Example: 2023-12-25 or 2023-12-25T23:00:00.000Z

Default behavior

  • If no filter is specified, the API returns data according to configured limits
  • OLD API: Returns all data for the location
  • NEW API: Returns the first 1000 results (modifiable with limit)

Compatibility

  • Requests without pagination parameters work identically on both versions
  • The new API adds optional features without breaking compatibility

Recommended performance (NEW API)

  • For large volumes (>10k records), use pagination with limit=100-500
  • For data export, use limit=5000 with multiple calls incrementing offset
  • The /weather/health endpoint allows knowing the total number of records before paginating

Practical examples

Retrieve all data from a city page by page

# Page 1
GET /weather/data/Lyon?limit=100&offset=0

# Page 2
GET /weather/data/Lyon?limit=100&offset=100

# Page 3
GET /weather/data/Lyon?limit=100&offset=200

Export data for a complete year

# Export in multiple passes of 5000 records
GET /weather/data/Lyon?from=2023-01-01&to=2023-12-31&limit=5000&offset=0
GET /weather/data/Lyon?from=2023-01-01&to=2023-12-31&limit=5000&offset=5000
GET /weather/data/Lyon?from=2023-01-01&to=2023-12-31&limit=5000&offset=10000

Check if data exists

# Retrieve just 1 result to test
GET /weather/data/Lyon?limit=1

API monitoring

# Check health status
GET /weather/health

# Check cache performance
GET /weather/health