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, address_validate]

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). BulkResult for validate and reverse jobs; BulkAddressValidateResult for address_validate jobs.

  • Array [
  • oneOf
    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"
    },
    {
    "row": 1,
    "id": "order-1001",
    "result": {
    "success": true,
    "data": {
    "verdict": {
    "input_granularity": "none",
    "geocode_granularity": "none",
    "address_complete": true,
    "has_unconfirmed_components": true,
    "has_inferred_components": true,
    "possible_next_action": "accept"
    },
    "address": {
    "formatted": "Oxford Street, Osu, La Dade Kotopon, Greater Accra — GA1838164",
    "components": [
    {
    "type": "house_number",
    "value": "string",
    "confirmation": "confirmed"
    }
    ]
    },
    "geocode": {
    "lat": 0,
    "lng": 0,
    "granularity": "region",
    "source": "gps_code",
    "gps_code": "string",
    "plus_code": "string",
    "hex": "string"
    },
    "landmark": {
    "name": "string",
    "slug": "string",
    "relation": "string",
    "lat": 0,
    "lng": 0,
    "distance_m": 0
    },
    "issues": [
    {
    "code": "string",
    "severity": "error",
    "message": "string",
    "suggestion": "string"
    }
    ],
    "notice": "string"
    },
    "meta": {
    "request_id": "c86825f0-d8ca-4ae1-8226-514cc48e05c0",
    "cached": false,
    "latency": "1.802457582s",
    "boundary_distance_m": 1.42,
    "near_grid_boundary": false
    }
    },
    "error": "string"
    }
    ],
    "created_at": "2024-07-29T15:51:28.071Z",
    "started_at": "2024-07-29T15:51:28.071Z",
    "completed_at": "2024-07-29T15:51:28.071Z"
    }