Create a Batch Job

Batch jobs allow you to execute many API calls in a single batch, which is much more efficient and faster than making hundreds or thousands of individual requests. When you create a batch, you define each endpoint you want to call, and then aWhere's platform steps through each internally and provides all the results at once.

Any GET request from any of our Version-2 APIs can be included in a batch. The batch job system treats each API request individually, which means you can easily identify which API request produced which results. It is also fault-tolerant, so that if one request resulted in an error, all the others will execute normally. Note that if you request a set of paged results, only the first page of results will be returned; be sure to use the limit and offset parameters of that API to get all the results you need.

Batch jobs are queued and executed in the order they are created, from across all customers using aWhere APIs. While many jobs can run concurrently, the rest are inserted into a queue and executed quite quickly. Use the Status and Results endpoint to monitor your job status and retrieve the results when complete.

Important: This API will return a job ID which you must retain; there is not currently an API to list all jobs that you've created.

Important: For the Fields and Weather API there is a limit of 10,000 requests per batch job. Due to its complex processes the Agronomics endpoint is limited 1,500 requests per batch job.

Note: The current conditions API cannot be included in batch jobs.

API Request

API Endpoints

HTTP Verbs and URIs

POST /v2/jobs
  • Create a batch job by sending all the API calls you want to make in the payload of this API.

Query String Parameters

No query string parameters are supported.

Request Body

Format

{
 "title":"{jobTitle}",
 "type":"{jobType}",
 "requests":[{
    "title":"{requestTitle}",
    "api":"{verb} {endpoint}"
    },{
    "title":"{requestTitle}",
    "api":"{verb} {endpoint}"
    },{ 
      ... 
    }
    ]
}

Property Descriptions

Name Description Valid Values Required?
{jobTitle} A name for the job, which can aid you in identifying the result set. Any string No
{jobType} The type of job. Currently this system only supports the type "batch." batch Yes
{requestTitle} A name for each individual request, which can aid in identifying each set of results within a batch. This need not be unique between all the jobs. Any string No
{verb} {endpoint} This is the actual API request you're asking the Batch Jobs system to call. It must be a valid aWhere endpoint and is expressed as the HTTP verb, a space, and the relative URI. For example:
GET /v2/weather/fields/1234/observations
GET plus a valid aWhere endpoint Yes

HTTP Headers

Remember to always send your OAuth2 Access Token in the Authorization header (see Authentication). This API doesn't require any additional headers.

API Response

Response HTTP Status Codes and Headers

This API returns standard HTTP status codes and headers for aWhere APIs. Additionally, this endpoint will return Location header provides the URL of the newly created data record. It looks like this:

Location: https://api.awhere.com/v2/jobs/{jobId}

Response Body

This API will insert the requested job into the queue and return the following payload with details about the job, including the Job ID. You must save this Job ID in order to retrieve the job's status and results.

{
 "jobStatus":"{jobStatus}",
 "jobId":{jobId},
 "title":"{jobTitle}",
 "type":"{jobType}",
 "dateRequested":"{dateRequested}",
 "queuePosition":{queuePosition}
}

Property Descriptions

Name Description
{jobStatus} The current status of the job. When initially created this will usually be queued but may also be running,done, cancelled, or purged.
{jobId} The Job ID. You will need this to retrieve the job status and results.
{jobTitle} The title you gave for the entire job.
{jobType} The type of job, which current is only ever batch.
{dateRequested} The timestamp of when the job was created.
{queuePosition} If the job is queued, this is its position in the queue.

Example

Request

Endpoint

POST /v2/jobs

Body

{
 "title":"Yesterdays Weather, All Fields",
 "type":"batch",
 "requests":[{
    "title":"Field 1 Yesterday",
    "api":"GET /v2/weather/fields/1/observations/2015-07-01?properties=temperatures,precipitation"
    },{
    "title":"Field 2 Yesterday",
    "api":"GET /v2/weather/fields/2/observations/2015-07-01?properties=temperatures,precipitation"
    },{
    "title":"Field 3 Yesterday",
    "api":"GET /v2/weather/fields/3/observations/2015-07-01?properties=temperatures,precipitation"
    },{
    "title":"Field 4 Yesterday",
    "api":"GET /v2/weather/fields/4/observations/2015-07-01?properties=temperatures,precipitation"
    },{
    "title":"Field 5 Yesterday",
    "api":"GET /v2/weather/fields/5/observations/2015-07-01?properties=temperatures,precipitation"
    }]
}

Response

HTTP Header

Location: https://api.awhere.com/v2/jobs/24023

Body

 {
 "jobStatus":"queued",
 "jobId":24023,
 "title":"Yesterdays Weather, All Fields",
 "type":"batch",
 "dateRequested":"2015-07-02T10:00:00Z",
 "queuePosition":3
}