Arc Integration Guide

Revised November 29, 2023

1 of 10

ContentsOverview

3

Score data requirements

3Legal3

Process

4

Getting Started

4Authentication

5Buildings and Transit

5Cities and Communities

6

Performance Scores

6Meters

6

Key Concepts

8

Rendered plaque animation

9Analysis and reporting

9Surveys

9

API Documentation

10

2 of 10

OverviewArc​ provides tools to measure and score the operational performance of spaces, buildings,and places.
The platform allows authorized apps to interact on behalf of authorized users with the datastored about their projects within the platform.
The API provides access to data for the following four types of projects:●●●●

Buildings (including spaces, such as commercial interiors)
CitiesCommunities
Transit

The API provides access to the following:
●
●
●
●
●
●

Basic project details
Performance scores
Meters (e.g., energy, water) for Buildings and Transit
Rendered plaque animation
Analysis and reporting
Embeddable surveys for Buildings and Transit

Score data requirements
Read more about the ​Version 4.1​ data needed to generate a performance score for a:●●●

Building project.
Transit project. Transit projects are a type of Building project, with different datarequirements for the Human Experience category score.
Cities or Communities project.

Legal
The Arc platform encourages and invites other companies, software developers and data
partners to utilize the API and create a better experience for our users. We also believe
strongly in upholding privacy and security of our users' data. In order to ensure that all
parties involved in data handling for our users are using best practices for security, privacy
3 of 10and user preferences, we ask that any entities developing tools on behalf of a customer firstcontact us and establish a business relationship with an agreement that covers thesepoints.
Developers working directly for a customer whose data is being interchanged can startright away.

Process
Outlined below is a typical process. Not all steps apply to all integrations, but this should
give a good sense of what to expect.
Action
Review integration guide
Checkpoint call to answer any questions
Sign business agreement
Sign up at developer.usgbc.org and subscribe to Arc data
dev products
Create test user accountReview documentation
Checkpoint call to answer any questions
Announce partnership (PR)*
Develop integration against Arc API (QAS)
Perform QA on partner integration
Enable Production access and switch connection to Production
Set up partner info in Apps section*Announce partnership (PR)*
Ongoing updates and partner communication

Owner
PartnerPartner and Arc
PartnerPartner
Arc
PartnerPartner and Arc
Partner and Arc
PartnerPartner and Arc
Partner and Arc
Arc
Partner and Arc
Arc* Items marked with an asterisk are optional for customers directly using the API. A partner is an entitythat will serve multiple customers.

Getting Started
This section provides a high-level summary of actions needed to work with performancedata, and the sections that follow go into each concept in more detail. More detailed
documentation can also be found at developer.usgbc.org, which can be access using
below access.
Please create an account at developer.usgbc.org and subscribe to Arc data dev APIs.
Once you have a subscription, you can get a subscription key. This subscription key isrequired to use any API and is used to differentiate you from any other partner. You will also
4 of 10

be able to go through details of each and every API using your developer account. Youwould also need a test user account to create a few test projects at ​qas.arconline.io in ourdevelopment environment, and then use these projects through API for your development.
If you don’t have a user account or are not able to subscribe to Arc data development
APIs, please reach out to the Arc team.
You start by authenticating the user and retrieving the list of projects that the user hasaccess to. From this list, you can choose the specific project you wish to work with. If this is aproject you will be interacting with regularly, we recommend that you map the LEED ID ofthis project in your application to minimize the calls required to identify the project.
Once you have the ID, you can retrieve a list of available meters for a building project. For
each meter ID, you can retrieve data (as interval readings), or submit data. Data submission
can include multiple readings in one POST, packaged as a JSON array.
Once data is submitted, you can invoke a score recomputation manually. If this is not done,
the system will recompute scores through its batch processed jobs, which can take up to afew hours depending on the queue size. Manual invocation will recompute the score within
5 minutes. This is recommended if you send data in batches. However, if your system sends
a continuous stream of data, then manual invocation is not necessary, and you can let thebackground jobs perform the recompute action.

Authentication
All requests are authenticated using a combination of an OAuth 2.0 style bearer token andan API subscription key. The API subscription key is generated and managed through theAzure platform. The token is retrieved using the login service.
All operations are performed on behalf of a user, and not as an authorized app. If a user
does not exist, they must first create a user account on the ​USGBC.org​ website.
The API will check the basic credentials to determine which projects they may access. Theuser information also determines which resources you can modify using PUT and POST
requests.

Buildings and Transit
The API treats each individual entity as a building. You will see the terms ‘project’ and‘building’ being used interchangeably in various places. For the purposes of the API, aproject and a building are interchangeable if you have the unique ID associated with it. This
ID is usually in the form of "LEED:" in the URL or responses.

5 of 10

Cities and Communities
The API treats each individual entity as a place. For the purposes of the API, the term
‘project’ is interchangeable with both ‘city’ and ‘community’ if you have the unique ID
associated with the place. This ID is usually in the form of "LEED:" in the URL or responses.

Performance Scores
Arc presents scores via the API for all project types. The request can include a parameter tospecify a historical time for which you need the score.
The score includes the scores for each individual category (or “racetrack”) - Energy, Water,Waste, Transportation, and Human Experience – and the maxima for each racetrack.

MetersFor buildings, all energy, water, and indoor air quality data is collected in the form of meters.
A building can have multiple meters associated with it, and meters are distinguished by theType ID. Each meter will capture time-series data with a start time, end time, and reading.
For energy and water, the reading is a consumption value (i.e., total consumption within thesupplied time period). For example, if the total energy consumed in a day is 100 units, then
you can provide this information in the following ways:
Method 1
This example shows one reading of total consumption over a 24-hour period.
[{“start_date”: “2015-03-01T00:00:00+05”,“end_date”: “2015-03-02T00:00:00+05”,“reading”: “100”}]

6 of 10

Method 2
This example shows the same consumption provided as 4 readings over a 6-hour period
each.
[{"start_date": "2015-03-01T00:00:00+05","end_date": "2015-03-01T06:00:00+05","reading": "20"},{"start_date": "2015-03-01T06:00:00+05","end_date": "2015-03-01T12:00:00+05","reading": "25"},{"start_date": "2015-03-01T12:00:00+05","end_date": "2015-03-01T18:00:00+05","reading": "30"},{"start_date": "2015-03-01T18:00:00+05","end_date": "2015-03-02T00:00:00+05","reading": "25"}]

Similarly, readings can be provided in high resolution, down to 1 second intervals (at the riskof transferring a large data volume), or aggregated up to a few hours, days, weeks, or evenmonths, depending on the application capabilities and tradeoff with the data volumes.

7 of 10

Key Concepts
Treatment of TimeInternally, all data are represented using a full date + time representation with a resolutionof seconds. Much of the data is interval data; that is, it applies to a time region rather thana point of time; examples include a meter reading for a month, or a carbon dioxide
measurement sampled over a 15-minute interval.
To represent this data, all measurements are associated with botha s​ tart_date​ and ​end_date​ value. These are both nominally full date + time values. If theintention is for it to apply to a date, the time portion should be set to zero(e.g., 2​ 013-02-01T00:00:00+5​); this is inferred if only a date string is provided. These values arerepresented using ISO8601 formats in all cases.
The range of time referenced by a ​start_date​, ​end_date​ pair include the time point encodedby s​ tart_date​, but do not include the point encoded by ​end_date​ (the range is [start, end).)
We often write these as a tuple (start_date, end_date).
To represent an entire day in January, you would use, for instance, (2013-01-01, 2013-01-02).
Because the end range excludes the point itself, the last point in that range would be
2013-01-01T23:59:59 as desired.
A similar strategy works for months; for instance, the month of January 2013 would berepresented by (2013-01-01, 2013-02-01).
Full datetimes are supported; for instance, the first fifteen minutes of a day would be(2013-01-01T00:00:00, 2013-02-01T00:15:00).
As a best practice, all timestamps should include time zone specification. This is not arequirement for data to be acceptable, but exclusion of time zone information introduces
the risk of misinterpreting time zone as it'll be assumed to be the same as building's physicallocation.
Fuel Types
Each meter is associated with a fuel type indicating the underlying quantity the meter istracking. The ‘Resource’ section in the developer portal contains a list of valid fuel types. In
the case of electricity, the fuel type also includes the grid or renewable source of theelectricity. Since each fuel type is associated with a set of emissions coefficients specific tothat grid or renewable source, you should attempt to provide the correct eGrid region andnot just the national average.
If you do not know the eGrid region, or your region is not listed in the available sources,
please contact us to identify or add yours.

8 of 10

Rendered plaque animation
For every project type, the Arc platform provides an animation of the performance score
racetracks, including total performance score in the middle.
This is an example of the animation for a certified Building project:​https://app.arconline.io/plaque/1000000117/1960ea90d643eb54e19be82bThis is an example of the animation for a non-certified Cities project:​https://app.arconline.io/plaque/1000096264/KM7RCVfeqDWAMHe0ajAGVNlZ

Analysis and reporting
The Arc platform provides analysis of data for all project types, as well as at an aggregatedlevel for a portfolio of Buildings.

Surveys
The Arc platform makes it possible for Buildings and Transit projects to survey users of abuilding. The survey provides anonymous data on Commuting patterns and users
Satisfaction and uses this data to calculate the Transportation category score and theHuman Experience category score, respectively.
The Re-Entry section includes separate surveys for facility managers and occupant
experience. These surveys contribute to the Re-Entry Comprehensiveness score. They do notcontribute directly to the Arc Performance Score.

9 of 10

API Documentation
Visit the Arc API page to:

1. Learn more about each end point.
2. Generate a subscription key.
3. Test APIs in a development environment.
There are two types of accounts:

1. A developer account ​manages Arc API subscriptions
2. A user account ​automates the exchange of data between Arc and a partner.

Get started:

1. Sign up for a developer account
2. Request a user account from c​ ontact@arcskoru.com

10 of 10