Skip to main content

Integrating GIS Data

Address suggestion files are typically uploaded through the Journey Builder UI, but you can automate this process using the epilot APIs. This guide covers programmatic integration of GIS (Geo Information System) data — uploading address CSV files and attaching them to journeys for address autocomplete functionality.

The process involves:

  1. Uploading a CSV File: Upload a CSV file containing the new address information.
  2. Validating Address Data: Validate the address data of the newly uploaded file
  3. Configuring Journey Settings: Attach the validated file to the journey configuration, so it's used in the address auto-complete functionality.

Follow the steps outlined in the detailed instructions below to implement this integration.

Prerequisites​

Please make sure to have the following parts set up already:

  • The CSV template downloaded. You can find it here
  • A Journey with an initial CSV file attached and an Address or Availability Block configured to use that CSV file
  • An Access Token setup with the permissions to work with the File API, Address Suggestions API, and Journey API

Steps to Integrate GIS data with epilot​

1. Upload the CSV File​

To automate the uploading of a CSV file containing address information, use the File API. This API allows the CSV file to be uploaded programmatically without manual intervention.

Tip: If you use JavaScript, you can use our epilot sdk to invoke the APIs via the sdk clients.

Required Steps:
There are 3 steps required to have the address suggestions file in the epilot ecosystem:

  1. Get a presigned URL in order to upload the file to an S3 Bucket via the uploadFile Endpoint
curl --location --request POST 'https://file.sls.epilot.io/v1/files/upload' \
--header 'Authorization: Bearer <AUTH-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "filename": "<FILE-NAME>.csv",
  "mime_type": "text/csv"
}'
  1. Upload the file via the previously received presigned URL (upload_url)
curl --location --request PUT '<UPLOAD-URL>' \
--header 'Content-Type: text/csv' \
--data-binary '@<PATH-TO-THE-FILE>.csv'
  1. Persist the uploaded file and create a file entity via the saveFile Endpoint. Use the returned s3ref from the first request.
curl --location --request POST 'https://file.sls.epilot.io/v1/files' \
--header 'Authorization: Bearer <AUTH-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "s3ref": <S3REF-OBJECT>,
    "filename": "<FILE-NAME>.csv",
    "access_control": "private",
    "_tags": [
        "address-suggestions"
    ]
}'

2. Validate the CSV File​

After uploading the CSV file, use the Address Suggestions API to validate the address data contained within the file.

This ensures that we provide correct address suggestions in Address or Availability Blocks.

Required Steps:

  1. Get the public_url from the response of the saveFile request (this shouldn't include "temp" in the path)
  2. Call the validateFile Endpoint by passing the public_url value as a query parameter.
  3. If the response returns a 200 status code, proceed to the next section. Otherwise, adjust the file according to the validation errors in the response.
curl --location --request GET 'https://address-suggestions-api.sls.epilot.io/v1/suggestions:validate?s3FileUrl=<PUBLIC-URL>' \
--header 'Authorization: Bearer <AUTH-TOKEN>'

3. Attach the file to the Journey​

Finally, link the validated CSV file to your journey using the Journey API.

Required Steps:

  1. Call the patchUpdateJourney Endpoint by passing the journey id you would like to update, with the value of the public_url under the property name settings.addressSuggestionsFileUrl.
curl --location --request PATCH 'https://journey-config.sls.epilot.io/v1/journey/configuration' \
--header 'Authorization: Bearer <AUTH-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "journeyId": "<JOURNEY-ID>",
  "settings.addressSuggestionsFileUrl": "<PUBLIC-URL>"
}'

Tip You can get the journey id by opening the journey in a new tab from the Journey Builder

Additional Resources​

For more details on each API and additional configuration options, see the epilot dev center.