Batch Geocode

Batch Geocode

The Batch Geocode task geocodes a table or file of addresses and returns the geocoded results. It supports CSV, XLS or table input. The task geocodes the entire file regardless of size.

Request URL

http://<analysis url>/BatchGeocode/submitJob

Request parameters

Parameter

Description

geocodeParameters (Required)

This includes parameters that help parse the file, as well the field lengths and a field mapping. This JSON is the output from AnalyzeGeocodeInput. It is important to inspect the field mapping closely and adjust it accordingly before submitting your job, otherwise your geocoding results may not be accurate. It is recommended to use the output from AnalyzeGeocodeInput and modify the field mapping instead of constructing this JSON by hand and passing it in.

Values

  • field_info—A list of triples with the field names of your input file/table, its field type (usually TEXT), and its allowed length (usually 255). A sample input looks like [('ObjectID', 'TEXT', 255), ('Address', 'TEXT', 255), ('Region', 'TEXT', 255), ('Postal', 'TEXT', 255)]
  • column_names—Submit the column names of your data if your data does not have a header row.
  • file_type—Either CSV, XLS, or table
  • column_delimiter—";", "\t", "|", or ","
  • text_qualifier—Either "\"" or "\'"
  • field_mapping—Field mapping between each input field and candidate fields on the geocoding service. Example: [['ObjectID', 'OBJECTID'], ['Address', 'Address'], ['Region', 'Region'], ['Postal', 'Postal']]
  • header_row_exists—Enter true or false.

Example: {"field_info": "[('ObjectID', 'TEXT', 255), ('SingleLine', 'TEXT', 255), ('Address', 'TEXT', 255), ('Region', 'TEXT', 255), ('Postal', 'TEXT', 255), ('PostalExt', 'TEXT', 255), ('Country', 'TEXT', 255), ('Source', 'TEXT', 255)]", "column_names": "", "file_type": "csv", "column_delimiter": ",", "text_qualifier": "", "field_mapping": "[['ObjectID', 'OBJECTID'], ['SingleLine', 'SingleLine'], ['Address', 'Address'], ['Region', 'Region'], ['Postal', 'Postal'], ['PostalExt', 'PostalExt'], ['Country', ''], ['Source', '']]", "header_row_exists": true}

geocodeServiceURL

Enter the REST URL of the geocode service that you want to geocode your addresses against. The URL must end in geocodeServer and allow batch requests. This could be a utility service or a geocoder that is anonymously accessible. The geocoding service must be configured to allow for batch geocoding. For more information, see: Configuring batch geocoding

outputType

Enter the format of the expected geocoding results.

Values: csv | xls | Feature Collection | Feature Service

inputTable

Syntax: The input table specification must include the following:

  • A URL to an input table
  • A service token to access the table

Note that if the table is a hosted table on the same portal, serviceToken is not required.

Example: {"url":"<table_url>","serviceToken":"<token>"}

inputFileItem

Syntax: The input file should be a portal item. Input the itemid of the item in the portal. The format of the item in the portal can be one of the following:

  • CSV
  • Microsoft Excel

Example: {"itemid":"<itemid_of_file>"}

sourceCountry

Enter a sourceCountry if all of your data is from the same country.

Example: US

category

Enter a category for more precise geocoding results if applicable. Note that some geocoding services do not support category.

Example: POI

outputFields

Enter the output fields from the geocoding service that you want returned in the results, separated by commas. To output all available outputFields, leave this parameter blank.

Example: score,match_addr,x,y

headerRowsToSkip

Describes on which row your data begins in your file or table. The default is 1 (since the first row contains the headers).

The default is 1.

Example: 1

outputName

If provided, the task will create a feature service of the results. You define the name of the service. If outputName is not supplied, the task will return a feature collection.

Syntax:
{
  "serviceProperties": {
    "name": "<service name>"
  }
}

context

context contains additional settings that affect task execution. Batch Geocode has the following two settings:

  • Extent (extent)—A bounding box that defines the analysis area. Only those points in inputLayer that intersect the bounding box are analyzed.
  • Output Spatial Reference (outSR)—The output features are projected into the output spatial reference.

Syntax:
{
"extent" : {extent}
"outSR" : {spatial reference}
}

f

The response format. The default response format is html.

Values: html | json

Response

When you submit a request, the service assigns a unique job ID for the transaction.

Syntax:
{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}

After the initial request is submitted, you can use jobId to periodically check the status of the job and messages as described in Checking job status. Once the job has successfully completed, use jobId to retrieve the results. To track the status, you can make a request in the following form:

http://<analysis url>/BatchGeocode/jobs/<jobId>

Access results

When the status of the job request is esriJobSucceded, you can access the results of the analysis by making a request in the following form:

http://<analysis url>/BatchGeocode/jobs/<jobId>/results/<output parameter name>?token=<your token>&f=json

Parameter

Description

geocodeResult

geocodeResult can be a feature collection JSON, or it contains the itemId of the geocoding job. itemId is either a feature service or a file, depending on the desired outputType.

Request example:
{"url": 
"http://<analysis url>/BatchGeocode/jobs/<jobId>/results/resultLayer"}

The result has properties for parameter name, data type, and value. The contents of value depend on the outputName parameter provided in the initial request.

  • If outputName was provided, value contains the URL to the feature service layer.
    {
     "paramName": "geocodeResult",
     "dataType": "GPString",
     "value": {
      "itemId": "3754b700a028480da874f6cd6e100e65",
      "url": "https://dev002096.esri.com/portal/sharing/rest/content/items/3754b700a028480da874f6cd6e100e65"
     }
    }
    
  • If outputName was not provided, value contains a feature collection.
    {
    "value":{"layerDefinition": {}, "featureSet": {}  }
    }
    

See Feature Output for more information about how the result layer or collection is accessed.

7/5/2017