# Jobs APIs
<a name="jobs-api-reference"></a>

The Amazon Location Jobs APIs provide programmatic access to bulk address validation capabilities through REST endpoints. All operations use standard AWS authentication.
+ **StartJob**: Initiates a new Amazon Location bulk processing job. For more information, See [StartJob](start-job-api.md).
+ **GetJob**: Retrieves comprehensive information about a specific job. For more information, See [GetJob](get-job-api.md).
+ **CancelJob**: Stops a running or pending job. For more information, See [CancelJob](cancel-job-api.md).
+ **ListJobs**: Retrieves a paginated list of jobs. For more information, See [ListJobs](list-jobs-api.md).

The following table presents business use cases that you can solve using Jobs API actions. Currently, `ValidateAddress` is the only supported action.


| **Business need** | **Job action** | 
| --- | --- | 
|  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/location/latest/developerguide/jobs-api-reference.html) | `ValidateAddress` | 

# StartJob
<a name="start-job-api"></a>

The `StartJob` operation initiates a new Amazon Location data processing job. You specify the action type, input and output Amazon S3 locations, and an IAM execution role that grants the service access to your buckets. The operation returns a job identifier, Amazon Resource Name (ARN), and initial status that you can use to monitor job progress.

You can request additional features using the `ActionOptions` parameter in `StartJob` requests. These features provide enhanced options for data processing and results.

For `ValidateAddress` jobs, the **Position** feature includes latitude and longitude coordinates in [World Geodetic System (WGS 84)](https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84) format. **CountrySpecificAttributes** includes additional data specific to each country, such as carrier route information, census data, and postal identifiers.

For more information, see [StartJob](https://docs.aws.amazon.com/location/latest/APIReference/API_geojobs_StartJob.html) in the *Amazon Location Service API Reference*.

For example requests, responses, and CLI commands for this API, see [How to start a job](https://docs.aws.amazon.com/location/latest/developerguide/starting-a-job.html).

## Use cases
<a name="start-job-use-cases"></a>
+ **Data migration and system consolidation:** Clean and standardize large volumes of address data when migrating between systems or consolidating multiple data sources into a unified database.
+ **Marketing campaign preparation:** Validate customer address databases before launching direct mail campaigns to reduce returned mail costs and improve delivery success rates.
+ **Database maintenance and compliance:** Regularly validate existing customer address databases to maintain data quality standards and meet shipping and logistics compliance requirements.

## Understand the request
<a name="start-job-request-parameters"></a>

The `StartJob` request requires configuration details that specify the job action, data locations, and permissions. This configuration determines how your data is processed and where results are stored.

The request includes the following parameters:

**Job action and permissions**  
Required parameters that define the operation type and access permissions.  
+ `Action`: The type of operation to perform. Currently only `ValidateAddress` is supported.
+ `ExecutionRoleArn`: IAM role ARN that Amazon Location assumes to access your Amazon S3 buckets during job execution.

**Input configuration**  
Required parameters that specify where to read input data and its format.  
+ `InputOptions`: Object containing input data configuration.
  + `Location`: Amazon S3 ARN or URI where input files are stored.
  + `Format`: Input data format. Currently only `Parquet` is supported.

**Output configuration**  
Required parameters that specify where to write results and their format.  
+ `OutputOptions`: Object containing output data configuration.
  + `Location`: Amazon S3 ARN or URI where output files are written.
  + `Format`: Output data format. Currently only `Parquet` is supported.

**Optional parameters**  
Parameters that provide additional job configuration and features.  
+ `Name`: Human-readable job name for easier identification. Must be 1-100 characters matching pattern `[-._\w]+`.
+ `ClientToken`: Idempotency token to ensure the same job is not created multiple times. Must be 1-64 characters matching pattern `^[!-~]+$`.
+ `ActionOptions`: Object containing additional features for the specified action.
  + `ValidateAddress`: Object containing options specific to address validation.
    + `AdditionalFeatures`: Array of feature names to include in results. Valid values:
      + `Position`: Includes latitude and longitude in [WGS 84](https://earth-info.nga.mil/index.php?dir=wgs84&action=wgs84) format for each validated address.
      + `CountrySpecificAttributes`: Includes additional data specific to each country, such as carrier route information, census data, and postal identifiers.

## Understand the response
<a name="start-job-response-details"></a>

The `StartJob` response provides essential information for monitoring and managing the newly created job. Use these values to track job progress and retrieve results when processing completes.

The response includes the following fields:

**Job identification**  
Unique identifiers for the created job.  
+ `JobId`: Unique job identifier used for monitoring and management operations.
+ `JobArn`: ARN that uniquely identifies the job within AWS.

**Job status and timing**  
Initial status and creation timestamp.  
+ `Status`: Initial job status. Always `Pending` for newly created jobs.
+ `CreatedAt`: Job creation timestamp in ISO 8601 format.

# GetJob
<a name="get-job-api"></a>

The `GetJob` operation retrieves information about a specific job, including its current status, configuration, timestamps, and any error information. Use this operation to monitor job progress and verify configuration details. For completed jobs, you can use this information to verify successful processing before accessing results.

For more information, see [GetJob](https://docs.aws.amazon.com/location/latest/APIReference/API_geojobs_GetJob.html) in the *Amazon Location Service API Reference*.

For example requests, responses, and CLI commands for this API, see [How to monitor job progress](https://docs.aws.amazon.com/location/latest/developerguide/monitoring-job-progress.html).

## Use cases
<a name="get-job-use-cases"></a>
+ **Job status and progress monitoring:** Track job lifecycle progression through pending, running, and completion states to determine when processing is complete and results are available for download. Monitor job status for workflow management and reporting.
+ **Error diagnosis:** Retrieve detailed error information when jobs fail, including specific error messages and failure reasons to troubleshoot processing issues.
+ **Configuration verification:** Confirm job configuration details including input/output locations, execution roles, and requested features before processing begins.

## Understand the request
<a name="get-job-request-parameters"></a>

The `GetJob` request requires only a single parameter to retrieve comprehensive information about a specific job. This simple request structure makes it easy to monitor job status and retrieve detailed configuration and processing information.

The request includes the following parameter:

**Job identification**  
Required parameter specifying which job to retrieve information about.  
+ `JobId`: The unique identifier of the job to retrieve. Must be 1-100 characters matching pattern `[-._\w]+`. This is the same identifier returned by the `StartJob` operation when the job was created.

## Understand the response
<a name="get-job-response-details"></a>

The `GetJob` response provides information about the specified job, including its current status, complete configuration, processing timestamps, and any error information. You can use this response to monitor job status and troubleshoot any errors that may arise.

The response includes the following fields:

**Job identification**  
Unique identifiers and basic job information.  
+ `JobId`: The unique job identifier used for monitoring and management operations.
+ `JobArn`: ARN that uniquely identifies the job within AWS.
+ `Name`: Human-readable job name if specified during job creation.

**Job status and lifecycle**  
Current job state and processing timeline information.  
+ `Status`: Current job status indicating processing state (Pending, Running, Completed, Failed, Cancelling, or Cancelled).
+ `CreatedAt`: Job creation timestamp in ISO 8601 format.
+ `UpdatedAt`: Last status update timestamp in ISO 8601 format.
+ `EndedAt`: Job completion timestamp in ISO 8601 format. Only present for jobs in terminal states.

**Job configuration**  
Complete job configuration as specified during creation.  
+ `Action`: The type of operation being performed (currently only `ValidateAddress` is supported).
+ `ExecutionRoleArn`: IAM role ARN used for accessing Amazon S3 buckets during job execution.
+ `InputOptions`: Input configuration including Amazon S3 location and data format.
+ `OutputOptions`: Output configuration including Amazon S3 destination and result format.
+ `ActionOptions`: Optional additional features requested for the job, such as `Position` or `CountrySpecificAttributes`.

**Error information**  
When a job fails, the response includes error details to help you diagnose and resolve the issue.  
+ `Error`: A `JobError` object containing details about the failure. This object includes the following fields:
  + `Code`: An error code that identifies the type of failure.
  + `Messages`: A list of human-readable messages that provide additional context for troubleshooting.

# CancelJob
<a name="cancel-job-api"></a>

The `CancelJob` operation stops a running or pending job. Only jobs in **Pending** or **Running** states can be cancelled. Cancellation is asynchronous, so you should monitor the job status to confirm completion. Cancelled jobs may have partial results in the output location depending on when cancellation occurs during processing.

For more information, see [CancelJob](https://docs.aws.amazon.com/location/latest/APIReference/API_geojobs_CancelJob.html) in the *Amazon Location Service API Reference*.

For example requests, responses, and CLI commands for this API, see [How to cancel a job](https://docs.aws.amazon.com/location/latest/developerguide/canceling-job.html).

## Use cases
<a name="cancel-job-use-cases"></a>
+ **Stop unnecessary processing:** Cancel jobs that were submitted with incorrect configuration, are no longer needed due to changed business requirements, or were started by mistake. This can prevent wasted resources and unnecessary charges.
+ **Resource and cost optimization:** Free up processing capacity by cancelling lower-priority jobs when higher-priority tasks need to be processed.

## Understand the request
<a name="cancel-job-request-parameters"></a>

The `CancelJob` request requires only a single parameter to identify which job to cancel. This simple request structure makes it easy to stop processing for jobs that are no longer needed.

The request includes the following parameter:

**Job identification**  
Required parameter that specifies which job to cancel.  
+ `JobId`: The unique identifier of the job to cancel. Must be 1-100 characters matching pattern `[-._\w]+`. This is the same identifier returned by the `StartJob` operation when the job was created. Only jobs in `Pending` or `Running` status can be cancelled.

## Understand the response
<a name="cancel-job-response-details"></a>

The `CancelJob` response confirms the cancellation request and provides the job's updated status. Because cancellation is asynchronous, you should use the `GetJob` operation to monitor the job until it reaches the `Cancelled` status.

The response includes the following fields:

**Job identification**  
Unique identifiers for the job being cancelled.  
+ `JobId`: The unique job identifier.
+ `JobArn`: Amazon Resource Name (ARN) of the job being cancelled.

**Cancellation status**  
Current job status after the cancellation request.  
+ `Status`: Job status immediately after the cancellation request. Typically `Cancelling` to indicate cancellation is in progress. The status transitions to `Cancelled` when cancellation completes. Use `GetJob` to monitor this transition.

**Note**  
Cancelled jobs may have partial results in the output location depending on when cancellation occurs during processing. Check the output location to determine if any partial data was written before cancellation completed. You are billed for the number of records that were processed and written to your output bucket before the job was cancelled.

# ListJobs
<a name="list-jobs-api"></a>

The `ListJobs` operation retrieves a paginated list of jobs with optional filtering capabilities. You can filter by job status and control the number of results returned. The operation supports pagination through next tokens, allowing you to retrieve large job lists efficiently.

For more information, see [ListJobs](https://docs.aws.amazon.com/location/latest/APIReference/API_geojobs_ListJobs.html) in the *Amazon Location Service API Reference*.

For example requests, responses, and CLI commands for this API, see [How to list jobs](https://docs.aws.amazon.com/location/latest/developerguide/listing-jobs.html).

## Use cases
<a name="list-jobs-use-cases"></a>
+ **Job inventory management:** Retrieve all jobs to audit processing history and track resource utilization across validation operations.
+ **Status-based monitoring:** Filter jobs by status to identify running jobs requiring attention or completed jobs ready for result retrieval.
+ **Operational reporting:** Generate reports on job execution patterns, success rates, and processing volumes for business analytics.
+ **Troubleshooting and debugging:** List failed jobs to identify patterns in processing errors and diagnose systematic issues.

## Understand the request
<a name="list-jobs-request-parameters"></a>

The `ListJobs` request accepts optional parameters for filtering and pagination. Without any parameters, the operation returns all jobs with default pagination.

The request includes the following optional parameters:

**Filtering options**  
Optional parameters to narrow the list of returned jobs.  
+ `Filter`: Object containing filter criteria.
  + `JobStatus`: Filter jobs by their current status. Valid values: `Pending`, `Running`, `Completed`, `Failed`, `Cancelling`, or `Cancelled`.

**Pagination controls**  
Optional parameters to control result pagination.  
+ `MaxResults`: Maximum number of jobs to return in a single response. Use this to control page size for large result sets.
+ `NextToken`: Pagination token from a previous `ListJobs` response. Include this token to retrieve the next page of results.

## Understand the response
<a name="list-jobs-response-details"></a>

The `ListJobs` response provides a paginated list of job summaries with configuration and status information for each job. Use the next token to retrieve additional pages when more results are available.

The response includes the following fields:

**Job list**  
Array of job summaries matching the filter criteria.  
+ `Entries`: Array of job summaries, including:
  + `Action`: Action performed by the job.
  + `CreatedAt`: Job creation timestamp in ISO 8601 format.
  + `EndedAt`: Job completion timestamp in ISO 8601 format. Only present for jobs in terminal states (Completed, Failed, or Cancelled).
  + `ExecutionRoleArn`: IAM role used for execution.
  + `InputOptions`: Input configuration object.
  + `JobArn`: Amazon Resource Name (ARN) of the job.
  + `JobId`: Unique job identifier.
  + `Name`: Job name if provided during creation.
  + `OutputOptions`: Output configuration object.
  + `Status`: Current job status.
  + `UpdatedAt`: Last update timestamp in ISO 8601 format.
  + `ActionOptions`: Additional features requested, if any.

**Pagination token**  
Token for retrieving additional results.  
+ `NextToken`: Token to include in the next `ListJobs` request to retrieve the next page of results. This field is only present when more results are available. The absence of this field indicates you have retrieved the last page.

**Note**  
Results maintain consistent ordering across pages. Use the `NextToken` from each response in subsequent requests to iterate through all pages of results.