# 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](/reference/addresses-v2-address-search#geocode-2) | At least one of `address`, `streetName`, or `localityName` |
| `reverseGeocoder` | [Reverse Geocode](/reference/addresses-v2-address-search#reverse-geocode-2) | Both `latitude` and `longitude` |
| `mailPoint` | [MailPoint](/reference/addresses-v2-address-search#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:

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

See [Addresses Additional Properties](/guides/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:

```csv
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
```

```json
[
  {"name": "address", "apiParameter": "address"}
]
```

For structured geocoding, map existing columns to individual components:

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

```json
[
  {"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:

```csv
customerAddressId,latitude,longitude
1,-35.32202098,149.14668176
```

```json
[
  {"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:

```json
{
  "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.

```json
{
  "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](https://tools.ietf.org/id/draft-goessner-dispatch-jsonpath-00.html) and [RFC 9535](https://datatracker.ietf.org/doc/rfc9535/) provide background. RFC syntax support should not be assumed beyond expressions accepted by the service.

## Next steps

- [Submit and run a batch](/guides/batches/quickstart)
- [Manage job states](/guides/batches/managing-jobs)