HomeGuidesRecipesAPI ReferenceChangelog
Log In
Guides

Bulk Site Upload

A walkthrough of the bulk site upload functionalities on Dashboard.

Overview

Bulk site upload allows you to interact with sites by uploading a CSV file to the Dashboard.

  1. Bulk site creation is useful for creating new sites, allowing you to pass in any site field information as needed.
  2. Bulk site update is useful for making edits to your existing sites by passing in the siteId and relevant changes.

How to: bulk site creation

  1. Navigate to the Sites tab and select Create sites.

  2. Select Bulk upload from a file.

  3. Download the template sites.csv and add your data to sheet. Once ready, drag and drop your file to the modal. See here for full list of columns in the template.

    Note: do not populate the column siteId for new site creation. This field is for site update.

    See here for file requirements.

  4. If there are no issues in the file submitted, you will see a success indicator of a green check mark.

  5. Warnings and Errors

    1. If there are issues with the file, these will be treated as a global warnings and errors. Examples of global errors are file size limitations or encoding errors. See here for a full list of warnings and errors you may encounter.

    2. If there are issues with the data you submitted, these will be treated as site level warnings and errors. _See here for a full list of warnings and errors you may encounter.

You can download the updated_sites.csv file which will now contain 2 additional columns: warnings and errors. These columns will contain recommendations to resolve the warnings and issues in each row.

🚧

Warnings may be ignored. These will not block you from submitting the data, but are flagged as irregularities from our side.

❗️

Errors may not be ignored. These are issues that must be fixed before we can accept the data.

Once all the errors have been resolved (warnings are optional), you can resubmit this same file with the two additional columns to resubmit the data. We will ignore the two additional columns so you do not need to remove them. Repeat this step as many times as necessary.

If there are still warnings, you will see an alert, but you can ignore these by selecting Skip. All sites will be created and viewable in the Sites tab of the Dashboard.

How to: bulk site update

Bulk site update follows the same workflow as bulk site creation in the Dashboard and utilizes the same template: sites.csv.

  1. In the template sites.csv, add the siteId for the site you want to update to the column named siteId.
  2. On the same row, update any column with the desired new value. Any fields without a value will not be updated and remain as is.
  3. Follow the same steps as above for bulk site creation to submit the the file and address any warnings or errors as needed. All sites will be updated and viewable in the Sites tab of the Dashboard.

File requirements

  • Supported file format: CSV only
  • Maximum file size: 1 GB
  • Maximum number of rows: 10,000

Template details: sites.csv

  • All field lengths have maximums of 255 characters excluding siteId and the enumerated fields. siteId has a value of 40 characters:sit_00000000-0000-0000-0000-000000000000.
FieldTypeRequiredNote
siteNamestringTRUE*Must be unique to your organization.
*Not required if siteId is present for an update
citystringFALSE
countrystringFALSEUse ISO 3166 country codes.
postalCodestringFALSE
regionstringFALSE
siteCodestringFALSE
siteNumberstringFALSE
subRegionstringFALSE
statestringFALSE
streetLine1stringFALSE
streetLine2stringFALSE
siteIdstringTRUE*Required to update a site.
*Not required to create a new site. Auto-generated value.
areaintegerFALSEMust be a positive value.
numberOfStoriesintegerFALSEMust be a positive value.
yearBuiltintegerFALSEMust be a positive value within 10 years of current year.
hvacHeatTypeenum (string)FALSESee enum list here.
hvacCoolTypeenum (string)FALSESee enum list here .
hvacVentTypeenum (string)FALSESee enum list here .
heatingFuelenum (string)FALSESee enum list here .
buildingTypeenum (string)FALSESee enum list here .
buildingTypeGroupenum (string)FALSESee enum list here .

Deprecated fields

facilityType

facilityType has been deprecated in favor of buildingType. This field will not show up in the sites.csv template, but can be added as a column and accepted via the bulk upload if required for a legacy integration.

recipient

recipient has been deprecated from the primary list of fields for a site. This field will not show up in the sites.csv template, but can be added as a column and accepted via the bulk upload if required for a legacy integration.

meterIds

meterIds has been deprecated from the create and update site flows. New site-to-meter mapping flows in the Dashboard coming in Q4 2024!

Warnings

Warnings may be ignored. They are flagged as irregularities from Arcadia's perspective.

NameDescriptionClassificationRemedy
UNUSED_COLUMNSColumns in spreadsheet are unusedGlobalN/A-- confirm data is not missing or column name is as expected
DUPLICATE_ADDRESSTwo sites with the same addressSiteN/A-- we recommend defining each site as a location with a unique address.

Errors

NameClassificationRemedy
FILE_SIZE_TOO_LARGEGlobalFile is too large. The maximum file size is 1GB.
INVALID_CSVGlobalUse the template provided to ensure file is a CSV
INVALID_ENCODINGGlobalFile has an invalid file encoding. We only support UTF-8 encoded files.
TOO_MANY_ROWSGlobalToo many sites in File. Reduce number of records to 10,000
MISSING_REQUIRED_COLUMNGlobalReview CSV file and ensure column name is present. Frontend global error.
NO_DATA_IN_FILEGlobalNo sites in file. Add at least 1 site to the CSV file
ERROR_OTHERGlobalOpen a support ticket on Zendesk to look into the unexpected error
SITE_DOES_NOT_EXISTSiteNo site with the specified ID was found.
SITE_ALREADY_EXISTSSiteA site with the same name already exists. Choose a different site name.
MISSING_REQUIRED_FIELDSiteReview the required fields here.
INVALID_VALUESiteReview the field types and valid values here.
DUPLICATE_SITENAME_IN_FILESiteTwo or more sites in the file have the same site name. Remove duplicates.