POST Async Batch Job enterprise only

Note

Batch job processing supports up to 1 million rows and is designed for large datasets.

The batch job geocoding service allows multiple locations to be geocoded asynchronously via POST request. This method is recommended for processing more than 100 locations or when you need to avoid timeout issues.

Resource URL

https://www.mapquestapi.com/geocoding/v1/batch/jobs

Resource Information

Response Formats	JSON
Authentication	Yes (Requires Key)
Rate Limited	Yes

Request Parameters

Request Parameter	Description	Required
key	The API Key, which is needed to make requests to MapQuest services.	Yes
type	The type of batch geocode job to create. Options: geocode (default), reverse	optional, defaults to geocode
startJob	Whether to start the job immediately after creation.	optional, defaults to true
inputDelimiter	Character used to delimit fields in the CSV input.	optional, defaults to ,

Response Object

id	The unique job identifier
status	The current job status
href	The MapQuest URL of the job details

Request Body

The request body must contain CSV-formatted text with the appropriate headers based on the job type.

For Geocode Jobs (type=geocode):

recId,q,in,lang,limit
001,Denver CO,USA,en-US,1
002,Boulder CO,USA,en-US,1
003,Aspec CO,USA,en-US,1

For Reverse Geocode Jobs (type=reverse):

recId,at,lang,limit
001,39.74001 -104.99202,en-US,1
002,40.01574 -105.27924,en-US,1
003,39.19002 -106.81818,en-US,1

CSV Field Descriptions

Geocode Job Fields:

• recId (optional): Record identifier. Auto-generated if empty
• q: Address or location to geocode
• in: Country code (e.g., USA, DEU)
• lang: Language code (e.g., en-US, de-DE)
• limit: Maximum number of results to return

Reverse Geocode Job Fields:

• recId (optional): Record identifier. Auto-generated if empty
• at: Latitude and longitude coordinates (format: lat lng)
• lang: Language code (e.g., en-US, de-DE)
• limit: Maximum number of results to return

Example Request

Creating a Geocode Job:

curl -X POST "https://www.mapquestapi.com/geocoding/v1/batch/jobs?key=YOUR_API_KEY&type=geocode&startJob=true" \
  -H "Content-Type: text/plain" \
  -d 'recId,q,in,lang,limit
001,Denver CO,USA,en-US,1
002,Boulder CO,USA,en-US,1
003,Aspec CO,USA,en-US,1'

Creating a Reverse Geocode Job:

curl -X POST "https://www.mapquestapi.com/geocoding/v1/batch/jobs?key=YOUR_API_KEY&type=reverse&startJob=true" \
  -H "Content-Type: text/plain" \
  -d 'recId,at,lang,limit
001,39.74001 -104.99202,en-US,1
002,40.01574 -105.27924,en-US,1
003,39.19002 -106.81818,en-US,1'

Initial Response

The initial POST request returns job metadata as JSON:

{
  "id": "abc123-def456-ghi789",
  "status": "submitted",
  "href": "https://www.mapquestapi.com/geocoding/v1/batch/jobs/abc123-def456-ghi789"
}

This endpoint only creates and optionally starts the job. The actual geocoding results will be available later via separate status and results endpoints.

Checking Job Status

Use the job ID from the href field to check processing status:

GET https://www.mapquestapi.com/geocoding/v1/batch/jobs/{jobId}?key=YOUR_API_KEY

Status Response

{
  "id": "abc123-def456-ghi789",
  "status": "completed",
  "href": "https://www.mapquestapi.com/geocoding/v1/batch/jobs/abc123-def456-ghi789"
}

Retrieving Results

Once completed, retrieve results using the job ID:

GET https://www.mapquestapi.com/geocoding/v1/batch/jobs/{jobId}/results?key=YOUR_API_KEY

Results are returned as CSV with the geocoded data:

recId|seqNumber|seqLength|position|address|title
1|1|1|(39.74001,-104.99202)|Denver, CO, United States|Denver, CO, United States
2|1|1|(40.01574,-105.27924)|Boulder, CO, United States|Boulder, CO, United States
3|1|1|(39.19002,-106.81818)|Aspen, CO, United States|Aspen, CO, United States

Job Status Values

Status	Description
submitted	Job has been received and submitted
queued	Job is queued and waiting to be processed
pending	Job is pending processing
inProgress	Job is currently being processed
completed	Job has finished processing successfully
stopped	Job has been stopped
failure	Job failed due to an error

Important Notes

• File Size Limits: Maximum 1 million rows or 500MB per CSV file
• Content-Type: Use text/plain for the request header
• Request Format: POST with query parameters and CSV body (not JSON)
• Authentication: Same API key as other endpoints, passed as query parameter
• Processing: This endpoint creates/starts the job; results retrieved separately
• Result Retention: Results are available for 24 hours after completion
• Rate Limits: Batch job requests count toward your daily API quota
• Error Handling: Failed locations are included in results with error details