Skip to main content

BulkJob

An async bulk processing job

idstring<uuid>

Job UUID

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
user_idinteger

Owner user ID

typestring

Job type

Possible values: [validate, reverse]

Example: validate
statusstring

Current job status

Possible values: [pending, processing, completed, failed, cancelled]

Example: processing
total_countinteger

Total number of rows to process

Example: 500
processed_countinteger

Number of rows processed so far

Example: 250
valid_countinteger

Number of successfully resolved rows

Example: 230
error_countinteger

Number of rows that failed

Example: 20
error_messagestring

Top-level error message (only present if job failed)

results object[]

Full results array (only included on single-job GET when completed)

  • Array [
    • rowinteger

    Row number (1-based)

    Example: 1
    inputstring

    Original input address

    Example: AK-484-9321
    validboolean

    Whether the address is valid and was resolved

    Example: true
    gps_namestring

    Canonical GPS name (if valid)

    Example: AKW4849321
    regionstring
    Example: Ashanti
    districtstring
    Example: Kwadaso
    areastring
    Example: Hemang
    postcodestring
    Example: AKW484
    latitudenumber<double>
    Example: 6.65008
    longitudenumber<double>
    Example: -1.6487
    quality_scorenumber<double>
    Example: 0.85
    google_maps_urlstring
    Example: https://www.google.com/maps/search/?api=1&query=6.650080,-1.648700
    errorstring

    Error message (if invalid)

    Example: unknown district code
  • ]
    • created_atstring<date-time>

    When the job was submitted

    started_atstring<date-time>

    When processing began

    completed_atstring<date-time>

    When the job finished (completed, failed, or cancelled)

    BulkJob
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": 0,
      "type": "validate",
      "status": "processing",
      "total_count": 500,
      "processed_count": 250,
      "valid_count": 230,
      "error_count": 20,
      "error_message": "string",
      "results": [
        {
          "row": 1,
          "input": "AK-484-9321",
          "valid": true,
          "gps_name": "AKW4849321",
          "region": "Ashanti",
          "district": "Kwadaso",
          "area": "Hemang",
          "postcode": "AKW484",
          "latitude": 6.65008,
          "longitude": -1.6487,
          "quality_score": 0.85,
          "google_maps_url": "https://www.google.com/maps/search/?api=1&query=6.650080,-1.648700",
          "error": "unknown district code"
        }
      ],
      "created_at": "2024-07-29T15:51:28.071Z",
      "started_at": "2024-07-29T15:51:28.071Z",
      "completed_at": "2024-07-29T15:51:28.071Z"
    }