Jobs API

Endpoints for managing background jobs.

Get Job Status

Endpoint: GET /api/job_status.php

Get the current status of a background job.

Parameters

  • job_id (required): Job ID

Response

{
  "status": "success",
  "job_status": "completed",
  "job": {
    "id": 456,
    "job_type": "hotspot_analysis",
    "status": "completed",
    "progress": 100,
    "params": { ... },
    "result": {
      "dataset_id": 789,
      "dataset_name": "Hot Spot Results",
      "table_name": "spatial_data_789"
    },
    "created_at": "2024-01-01T00:00:00Z",
    "started_at": "2024-01-01T00:01:00Z",
    "finished_at": "2024-01-01T00:05:00Z"
  }
}

Job Statuses

  • queued: Job is waiting to be processed

  • running: Job is currently being processed

  • completed: Job completed successfully

  • failed: Job failed with an error

Example

curl -X GET "https://example.com/api/job_status.php?job_id=456" \
  -H "Cookie: PHPSESSID=..."

Cancel Job

Endpoint: POST /api/job_cancel.php

Cancel a queued or running job.

Request Body

{
  "job_id": 456
}

Response

{
  "status": "success",
  "message": "Job cancelled successfully"
}

Notes

  • Only queued or running jobs can be cancelled

  • Completed or failed jobs cannot be cancelled

  • Users can only cancel their own jobs (admins can cancel any job)

List User Jobs

Endpoint: GET /api/jobs/status.php

List all jobs for the current user.

Parameters

  • status (optional): Filter by status (queued, running, completed, failed)

  • job_type (optional): Filter by job type

  • limit (optional): Maximum results (default: 50)

  • offset (optional): Result offset (default: 0)

Response

{
  "status": "success",
  "jobs": [
    {
      "id": 456,
      "job_type": "hotspot_analysis",
      "status": "completed",
      "progress": 100,
      "created_at": "2024-01-01T00:00:00Z",
      "finished_at": "2024-01-01T00:05:00Z"
    }
  ],
  "total": 10,
  "limit": 50,
  "offset": 0
}

Example

curl -X GET "https://example.com/api/jobs/status.php?status=running&limit=10" \
  -H "Cookie: PHPSESSID=..."

Job Result Structure

Completed jobs include a result field with job-specific information:

Hot Spot Analysis Result

{
  "dataset_id": 789,
  "dataset_name": "Hot Spot Results",
  "table_name": "spatial_data_789",
  "row_count": 1000,
  "storage_type": "table"
}

Outlier Analysis Result

{
  "dataset_id": 790,
  "dataset_name": "Outlier Results",
  "table_name": "spatial_data_790",
  "row_count": 50,
  "outlier_count": 50
}

Nearest Analysis Result

{
  "dataset_id": 791,
  "dataset_name": "Nearest Results",
  "table_name": "spatial_data_791",
  "row_count": 500,
  "source_dataset_id": 123,
  "target_dataset_id": 124
}

Error Handling

Failed jobs include an error_message field:

{
  "status": "failed",
  "error_message": "Dataset not found",
  "job": {
    "id": 456,
    "status": "failed",
    "error_message": "Dataset not found"
  }
}