Skip to content
Aireon Developers
Navigation

Poll a 3D extract job

Reads the job directory on disk (cache/building3d/jobs/<jobId>/): result.json, written by the worker when it finishes, decides ready (ok) or error (with the message); until then state.json - written by the route at spawn time and updated by the worker with a phase (geocoding/locating, tile, clip, build, zip, email) - reports queued or running. Disk is the truth, so a poll may hit either pm2 cluster worker. A job still running with no update for 60 minutes is reported as error (stale). When the directory has been evicted, the 24 h Redis mirror is consulted as a fallback and a formerly ready job is reported as error (nothing left to download); with neither, 404.

Accepts the token in the token header or as ?token= so the URL can be polled from a Grasshopper HTTP component or a browser.

GET
https://res.aireon.ch/res_api/building3d-extract/status/{jobId}

Authorization

  • ResApiToken
    optional
    API key in header
  • ResApiTokenQuery
    optional
    API key in query

Path parameters

  • jobId
    string
    required

    Job id from the 202 of POST /res_api/building3d-extract (UUID v4).

    format: uuid · pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

Query parameters

  • token
    optional
    string

    The RES API token as a query parameter - alternative to the token header for links and header-less HTTP fetches (Grasshopper). Treat the resulting URL as a credential.

Returns

200

Current job state. files is empty until ready; downloadUrl is set only when ready.

JSON
  • jobId
    string
    required
    format: uuid
  • status
    queued
    or
    running
    or
    ready
    or
    error
    required

    queued: accepted, worker not started yet; running: worker in progress (see phase); ready: result.json says ok - download now; error: failed, stale, or evicted - see error.

  • files
    array of
    object
    required

    Downloadable members (empty until ready).

    • name
      string
      required

      Member name, usable as {file} on the download endpoint.

    • bytes
      integer
      required
      minimum: 0
  • error
    string | null
    required
  • createdAt
    string | null
    required
    format: date-time
  • updatedAt
    string | null
    required

    Last state change; the worker's finishedAt once a result exists.

    format: date-time
  • phase
    optional
    string | null

    Worker progress while running (starting, geocoding or locating, tile, clip, build, zip, email), done when ready, failed on error.

  • address
    optional
    string | null

    Address (or resolved label) of the request.

  • radius_m
    optional
    number | null
  • statusUrl
    optional
    string
  • downloadUrl
    optional
    string | null

    Set only when status is ready.

400

jobId is not a UUID v4.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

401

Authentication missing or invalid.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

403

Authenticated but not permitted.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

404

Resource not found.
JSON
  • error
    string
    required

    Human-readable error description.

  • message
    optional
    string

    Optional underlying error message.

Type to search…

↑↓ navigate↵ selectEsc close