On this page

Copy page

Documentation

Files and Mappings

Use this guide to choose a batch job type, configure CSV inputs and outputs, and map response fields with JSONPath.

Choose a job type

type	Addresses v2 endpoint	Required CSV input mappings
addressGeocoder	Geocode	At least one of address, streetName, or localityName
reverseGeocoder	Reverse Geocode	Both latitude and longitude
mailPoint	MailPoint	address

For geocoder jobs, supply parameters.matchType. Use the values documented in the Batches schema, such as Address, rather than assuming every Addresses API option is supported by Batches.

Job-wide multi-value settings use JSON arrays:

Code
{
  "matchType": "Address",
  "dataset": ["gnaf", "continuousAddress"],
  "additionalProperties": ["localGovernmentArea", "asgsMain"]
}

See Addresses Additional Properties for meanings and access requirements. The Batches schema lists the values supported for each job type.

Prepare the CSV

Use UTF-8 encoding and a header row. Every input.format[].name must match an input column. A mapped column becomes an API parameter for each row. Unmapped input columns are still copied to the output unless explicitly excluded.

For a full-address geocoder job:

Code
customerAddressId,address
1,UNIT 1 42-50 CLIFF RD EPPING NSW 2121
2,UNIT 4503 LEVEL 45 105 CLARENDON ST SOUTHBANK VIC 3006
3,LOT 304 LACHLAN DR OAKHURST QLD 4650

Code
[
  {"name": "address", "apiParameter": "address"}
]

For structured geocoding, map existing columns to individual components:

Code
customerAddressId,number,street,streetType,suburb,state,postcode
1,113,Canberra,AV,Griffith,ACT,2603

Code
[
  {"name": "number", "apiParameter": "streetNumber1"},
  {"name": "street", "apiParameter": "streetName"},
  {"name": "streetType", "apiParameter": "streetType"},
  {"name": "suburb", "apiParameter": "localityName"},
  {"name": "state", "apiParameter": "stateTerritory"},
  {"name": "postcode", "apiParameter": "postcode"}
]

For reverse geocoding:

Code
customerAddressId,latitude,longitude
1,-35.32202098,149.14668176

Code
[
  {"name": "latitude", "apiParameter": "latitude"},
  {"name": "longitude", "apiParameter": "longitude"}
]

Coordinates are in decimal degrees using the underlying Addresses API's default GDA94 CRS. Individual rows are processed by that API and can return no match or an error even when the batch configuration is valid.

Provide file access

The service must be able to read input.file from an HTTP, HTTPS, or FTP URL. A protected FTP file can use separate credential fields:

Code
{
  "file": "ftp://example.com/input.csv",
  "username": "YOUR_FTP_USERNAME",
  "password": "YOUR_FTP_PASSWORD",
  "format": [{"name": "address", "apiParameter": "address"}]
}

Keep file credentials out of source control. Passwords returned in job responses are masked.

For results:

• Omit output.file to receive batchInfo.downloadPath after completion. This sets returnDownloadLink=true
• Supply a writable FTP destination to have the service write a CSV there. HTTP and HTTPS output destinations are not supported
• With an output destination, returnDownloadLink defaults to false. Set it to true if you also want a download link

Choose output columns

Each output mapping has:

• name: the output CSV column header
• source: a JSONPath expression applied to the underlying API response

Input columns are included before mapped output columns. Output headers must be unique and must not collide with input headers. excludeInputColumns names must exist in the input file.

Code
{
  "format": [
    {"name": "Matched Address", "source": "$.features[0].properties.formattedAddress"},
    {"name": "Address ID", "source": "$.features[0].properties.addressId"},
    {"name": "Parcel ID", "source": "$.features[0].properties.cadastralIdentifier"},
    {"name": "LGA", "source": "$.features[0].properties.localGovernmentArea.lgaName"},
    {"name": "Meshblock 2021", "source": "$.features[0].properties.asgsMain[?(@.censusYear == 2021)].mbId"}
  ],
  "excludeInputColumns": ["address"]
}

Request localGovernmentArea and asgsMain in the job's additional properties for the related output fields above.

JSONPath examples

Expression	Result
$.features[0].properties.localGovernmentArea.lgaName	LGA name from the first feature
$.features[0]..lgaName	Recursive search for any lgaName beneath the first feature
$.features[0].properties.asgsMain[?(@.censusYear == 2011)].mbId	Mesh Block ID for the ASGS object with census year 2011
$.features[*].properties.addressId	Address IDs from all returned features
$.properties.dpid	DPID from a MailPoint response, which is a single Feature

The first feature is selected only when your expression uses [0]. Other expressions can extract any part of the response.

• No matches produce an empty CSV value
• One scalar match produces that value
• One object or array is serialised as JSON
• Multiple matches are serialised as a JSON array
• A row response that is not a Feature or FeatureCollection produces blank mapped output values

The original JSONPath proposal and RFC 9535 provide background. RFC syntax support should not be assumed beyond expressions accepted by the service.

Next steps

• Submit and run a batch
• Manage job states