Measurement Data Schema

Instructions

Below are file templates to utilize for your future data upload(s). Your upload must match the template exactly in order to be an acceptable input. Once you upload, your files will be validated to verify whether it meets the accepted template requirements.

Accepted File Types

• Comma Separated Value files (.csv) with string fields being optionally qualified by Double Quotes (see examples below)
• Tab Separated Value files (.tsv) with string fields being optionally qualified by Double Quotes (see examples below)

Customer Data File

File requirements

• Customer Data file names must begin with customer_data_ and end with the appropriate file type suffix (.csv or .tsv)
• If providing a csv file, if any delimiters are present in any field values, all values must be wrapped in double quotes
• Files must have a header row that contains all required fields, and a field name for each preferred data column provided
• The location of each Premise must be included by either providing both latitude and longitude columns or by providing a premise_address field. If both are available, Recurve prefers latitude and longitude. A mix of both types of address requirements across customers is acceptable (ie. It's acceptable to provide address for Customer A, and provide lat/long for Customer B in the same file)
• "Null" values should only be passed as empty values

Examples of acceptable file names

• customer_data__20240204.csv
• customer_data_westernRegion.csv

Examples of unacceptable file names

• West-region-customer_data_.csv (does not begin with service_point_data)
• customer_data_Jan2024.txt (does not end in appropriate file type suffix)

Field Name	Example Field Values	Acceptable Data Type	Field Requirements	Required or Preferred?	Nullable "Null" values should only be passed as empty values	Description
service_point_id	"“9471297459” “df-443-jk”"	STRING	An identifier for a particular service point. This identifier should remain unchanged across data uploads.	Required	No	A specific location at a premise where utilities supply service, or where usage occurs. Multiple service_point_ids can belong to a single premise_id. For example, a single premise_id will often have 1 electric and 1 gas service_point_id. Not to be confused with a meter_id. If a physical meter was replaced at a specific location, the service_point_id would remain unchanged, but the meter_id would change.
fuel_type	“gas” “electricity”	“gas” / “electricity”	Must contain one the two allowed values.	Required	No	Type of energy load being measured at service point. Should be electric or gas.
premise_id	“Efa43-98323” “553423”	STRING	This is a location identifier that can connect all meters at a given location and should remain unchanged across data uploads	Required	No	Unique identifier for the address/physical location where the utility supplies a service (gas or electric meter). Typically there should only be a single premise_id for a given site, especially for residential services. Multiple service_point_ids can belong to a single premise_id.
premise_address	“440 N Barranca Ave #8958, Covina, CA 91723”	STRING	Street address, city, state abbreviation, zipcode, or null if latitude / longitude is provided.	Required	Yes (see requirements)	The address of the site as street number, street, city, state, zip code. For all address fields, we are seeking site address information as opposed to billing address information.
premise_latitude	37.8957507	FLOAT	A valid latitude or null if premise_address is provided.	Required	Yes (see requirements)	Latitude for the location - can be generated by Recurve from premise_address field if not provided.
premise_longitude	-122.552748	FLOAT	A valid longitude or null if premise_address is provided.	Required	Yes (see requirements)	Longitude for the location - can be generated by Recurve from premise_address field if not provided.
timezone	“America/Los_Angeles” “America/Chicago”	Valid TZ Name	A valid TZ Name per the current version of the tx database. Values can be found here: https://cloud.google.com/looker/docs/reference/param-view-timezone-values	Required	No	Valid timezone for the customer, based on the tx database
sector	“commercial” “residential” "industrial	“commercial” / “residential” / "industrial"	Must contain one the three allowed values.	Required	No	High level sector classification for the customer
naics_code	“541690” “812113”	Valid NAICS code	A valid NAICS code (not group!) for the premise if sector is ”commercial” or null for residential premises.	Required	Yes (see requirements)	Any valid NAICS code per https://www.census.gov/naics/
rate_code	“RES9434”	STRING		Required	No	Customer billing rate code. Any rate/tariff supported by the utility in question, for example, https://www.pge.com/tariffs/index.page
is_net_metering	“true” “false”	“true” / “false”	Only applies to electric service points. If uncertain for electric service point, default should be false. If gas service point, should always be false.	Required	No	Indicates presence of any energy generation at the service point.
is_low_income	“true” “false”	“true” / “false”		Preferred	Yes	Low/Medium income status flag
account_id	“834712387” “23bed-98ae"	STRING		Preferred	Yes	Unique identifier for a customer's account, this account may be linked to numerous premises and meters, especially in the case of commercial customers
service_agreement_id	"9876543210"	STRING		Preferred	Yes	Unique identifier for a customer at a particular service_point. This allows us to connect a service point to specific customers' demographics and financials, such as NAICS code and rate code.
customer_name	"Smith, John" “Recurve Analytics, Inc"	STRING		Preferred	Yes	Full name of customer
customer_phone_number	“8005551212” “1-800-555-1212”	STRING		Preferred	Yes	Phone number for customer
customer_email	"john.smith@recurve.com" "recurveanalytics@recurve.com"	STRING		Preferred	Yes	Email address for customer
customer_language_preference	“en” “es” “Spanish” “English”	STRING		Preferred	Yes	Customer language preference
climate_zone	“Mixed-Dry” “Cold”	Valid Climate Zone Value	Building America Climate Zones can be found here: https://atlas.eia.gov/datasets/eia::climate-zones-doe-building-america-program/about	Preferred	Yes	Building America Climate Zone
CA_climate_zone	“CZ10” “CZ14”	Valid California Climate Zone Value	Only applies to California customers. California Building Climate Zones can be found here: https://gis.data.ca.gov/documents/CAEnergy::building-climate-zones/about	Preferred	Yes	California Climate Zone
utility_name	"SCE" "PG&E"	STRING		Required	No	Name of Utility. If energy_provider_name is populated, should be the long spelled out version of the name of the utility delivering the energy, or the IOU
energy_provider_name	"PG&E" "SCE" "MCE"	STRING		Preferred	Yes	Name of energy provider - can be different from the Utility name in certain cases
service_agreement_open_date	2020-08-21 2020-08-25	STRING	Must contain a date.	Required	No	Date that the service agreement was opened (applies to the service_agreement_id)
service_agreement_close_date	2020-08-21 2020-08-25	STRING	Must contain a date, even if the agreement has not yet ended.	Required	No	Date that the service agreement was closed (applies to the service_agreement_id). If the agreement has not yet closed, provide a date far in the future, such as 9099-12-31
service_agreement_status	"Open" "Closed"	STRING		Preferred	Yes	Is the service agreement open or closed (applies to the service_agreement_id)

Sample Customer Data

service_point_id	premise_id	fuel_type	premise_address	premise_latitude	premise_longitude	timezone	sector	naics_code	rate_code	is_net_metering	is_low_income	customer_name	customer_phone_number	customer_email	customer_language_preference	climate_zone	ca_climate_zone	utility_name	FIELD20
676312139	1234	Electric	100 California Ave, San Francisco, CA, 94111	37.817388	-122.372144	America/Los_Angeles	commercial	922600	B4-100	TRUE	TRUE	John Smith	(800)555-1212	customer1@example.com	english	Cool	Z03	Electrons R' Us
676312140	5678	Electric	101 California Ave, San Francisco, CA, 94111	37.817388	-122.372144	America/Los_Angeles	commercial	922600	B4-100	TRUE	TRUE	John Smith	(800)555-1212	customer2@example.com	english	Cool	Z03	Electrons R' Us
676312141	9101	Electric	102 California Ave, San Francisco, CA, 94111	37.817388	-122.372144	America/Los_Angeles	commercial	922600	B4-100	TRUE	TRUE	John Smith	(800)555-1212	customer3@example.com	english	Cool	Z03	Electrons R' Us
676312142	2134	Electric	103 California Ave, San Francisco, CA, 94111	37.817388	-122.372144	America/Los_Angeles	commercial	922600	B4-100	TRUE	TRUE	John Smith	(800)555-1212	customer4@example.com	english	Cool	Z03	Electrons R' Us

---

Project Intervention Data File

(File not required if using Project Hub enrollment to collect project data)

File requirements

• Project Intervention Data Files must start with project_intervention_data_ and end with the appropriate file type suffix (.csv or .tsv)
• If providing a csv file, if any delimiters are present in any field values, all values must be wrapped in double quotes
• Files must have a header row that contains all required fields, and a field name for each preferred data column provided
• "Null" values should only be passed as empty values
• Should include data at the intervention level, and then the interventions aggregate into projects - there should not be a need for any pre-aggregated project data

Examples of acceptable file names

• project_data__20240204.csv
• project_data_june2024.csv

Examples of unacceptable file names

• West-region-project_data_.csv (does not begin with service_point_data)
• customer_data_Jan2024.txt (does not end in appropriate file type suffix)

Field Name	Example Field Values	Acceptable Data Type	Field Requirements	Required or Preferred?	Nullable "Null" values should only be passed as empty values	Description
included_service_point_ids	"9471297459, 9471297000” “df-443-jk”	STRING	Should include ALL Service Point Identifiers for the intervention. This list of service point IDs must be separated by commas and all wrapped in double quotes.	Required	No	A specific location at a premise where utilities supply service, or where usage occurs. Multiple service_point_ids can belong to a single premise_id. For example, a single premise_id will often have 1 electric and 1 gas service_point_id. Not to be confused with a meter_id. If a physical meter was replaced at a specific location, the service_point_id would remain unchanged, but the meter_id would change.
intervention_start_date	2020-08-21 2020-08-25	DATE		Required	No	Date work began on intervention
intervention_end_date	2024-10-1 2024-11-2	DATE		Required	No	Date work completed on intervention
measure_category	"Lighting" "Heat Pump Water Heater"	STRING	Standard Measure Categories will be provided by Recurve.	Preferred	No	Recurve defined measure categories - to be mapped based on the provided measure name.
measure_name	"Heat Pump Retrofit" "Heat Pump Water Heater" "Attic Insulation"	STRING		Required	No	Client provided measure name information
contractor	"John Doe's Energy Efficiency Co" "Best Lighting Upgrades Inc"	STRING		Required	No	Name of contractor or aggregator performing the work of the measure install
effective_useful_life	12	INTEGER		Required	No	Expected number of years the installed measure will be useful.
predicted_savings_kwh	1000.00	FLOAT		Required	Yes	Predicted measure savings for use in realization rate (kWh)
predicted_savings_therms	30.00	FLOAT		Required	Yes	Predicted measure savings for use in realization rate (therms)
program_name	"Utility Demand Flexibility Program" "Summer Peak Reduction Program"	STRING		Required	No	Name of program to include this work
intervention_id	"project_d2_799" "ee_882"	STRING		Required	No	Unique id for the intervention/measure. If intervention id is provided, it will take priority in the user display.
contractor_address	“364 Ridgewood Ave, Mill Valley, CA, 94941”			Preferred	Yes
provided_project_id	"p_123" "ee_005"	STRING		Preferred	Yes	Aggregator or other provided project id. This can be repeated across multiple interventions (i.e. multi measure projects)
exante_annual_savings_kwh	500.00	FLOAT		Preferred	Yes	Deemed measure gross annual electricity savings (kWh)
exante_annual_savings_therms	40.00	FLOAT		Preferred	Yes	Deemed measure gross annual electricity savings (therms)
cost_currency	"USD"	STRING		Preferred	Yes	The currency used with the costs provided. For display purposes only.
cost_customer	70.00	FLOAT		Preferred	Yes	The cost that the customer incurred for the intervention.
cost_incentive	15.00	FLOAT		Preferred	Yes	The incentive provided for the intervention.
cost_utility	15.00	FLOAT		Preferred	Yes	The cost that the utility incurred for the intervention, separate from cost paid by customer or incentives.
num_units	2	INTEGER		Preferred	Yes	The number of units installed with the intervention.
equipment_make	"Goodman"	STRING		Preferred	Yes	The make associated with the intervention.
equipment_model	"2.5 Ton SEER20"	STRING		Preferred	Yes	The make associated witht the intervention.
measure_details	"integrated" "split system"	STRING		Optional	Yes	An optional field to include any extra details about the measure, such as the configuration information.

Sample Project Intervention Data

included_service_point_ids	intervention_start_date	intervention_end_date	measure_category	contractor	effective_useful_life	predicted_savings_kwh	predicted_savings_therms	program_name	intervention_id	contractor_address	provided_project_id	exante_annual_savings_kwh	exante_annual_savings_therms	cost_currency	cost_customer	cost_incentive	cost_utility	num_units	equipment_make	equipment_model
9972820192, 9824383544	5/28/20	6/9/20	Heat Pump Water Heater	John Doe's Energy Efficiency Co	15	1433.58	41.33	Electrification Program	project_409	734 Main St, Anytown, CA, 90210	ee_147	759.06	22.19	USD	136.92	33.16	22.43	1	Goodman	2.5 Ton SEER20
9744285192, 9903503221	7/8/20	7/20/20	HVAC Retrofit	Best Lighting Upgrades Inc	11	837.2	27.62	Summer Peak Reduction Program	project_325	806 Main St, Anytown, CA, 90210	ee_978	927.97	39.46	USD	95.22	31.61	44.53	1	Trane	1.5 Ton SEER21
9348479924, 9268111751	2/7/20	2/19/20	Heat Pump Water Heater	Best Lighting Upgrades Inc	15	1370.74	12.08	Electrification Program	project_255	552 Main St, Anytown, CA, 90210	ee_993	914.67	37.06	USD	68.21	31.09	41.58	1	Carrier	2.5 Ton SEER20
9625885908, 9805860088	12/16/20	12/28/20	Heat Pump Water Heater	Best Lighting Upgrades Inc	15	1481.62	34.69	Electrification Program	project_647	177 Main St, Anytown, CA, 90210	ee_713	244.38	16.88	USD	189.98	23.07	11.35	1	Goodman	2.5 Ton SEER20
9017942800, 9791343992	4/5/20	4/17/20	Heat Pump Water Heater	Best Lighting Upgrades Inc	15	547.82	32.07	Electrification Program	project_828	815 Main St, Anytown, CA, 90210	ee_418	526.57	14.11	USD	191.43	22.21	49.84	1	Carrier	1.5 Ton SEER21

---

Service Point Interval Data File

File requirements

• Service Point Interval Data file names must begin with service_point_data_ and end with the appropriate file type suffix (.csv or .tsv)
• If providing a csv file, if any delimiters are present in any field values, all values must be wrapped in double quotes
• Files must have a header row that contains all required fields
• Note that at this time, all Interval Data fields are required (none are Preferred)
• Electric: Must be hourly or 15 minute interval data
• Gas: Must be daily interval data
• "Null" values should only be passed as empty values

Examples of acceptable file names

• service_point_data_20240204.csv
• service_point_data_westernRegion.csv

Examples of unacceptable file names

• West-region-service-point-data.csv (does not begin with service_point_data)
• service_point_data.txt (does not end in appropriate file type suffix)

Field Name	Example Field Values	Acceptable Data Type	Field Requirements	Required or Preferred?	Nullable "Null" values should only be passed as empty values	Description
service_point_id	“9471297459” “df-443-jk”	STRING	An identifier for a particular service point. This identifier should remain unchanged across data uploads.	Required	No	A specific location at a premise where utilities supply service, or where usage occurs. Multiple service_point_ids can belong to a single premise_id. For example, a single premise_id will often have 1 electric and 1 gas service_point_id. Not to be confused with a meter_id. If a physical meter was replaced at a specific location, the service_point_id would remain unchanged, but the meter_id would change.
start	“2024-07-23 18:00:00 UTC” “2022-04-09T15:00:00-07:0”	TIMESTAMP	Valid date and time including timezone in ISO 8601 format	Required	No	Timestamp that indicates the start of the interval read
usage	32.44502 0.9754912312	FLOAT	Electric: Must be hourly or 15 min interval data represented by kWh Gas: Must be daily interval data represented by Therms Must be a positive usage value. (If total usage for a given start is negative, it should be sent as a positive value with “received” as the direction value per below).	Required	Yes	Amount of energy consumed between the starting interval read and the next interval read. Can be null if known to be missing.
direction	“received” “delivered”	“received” / “delivered”		Required	No	Direction of energy flow to indicate whether the interval read is being received by the Utility from the customer, or delivered from the Utility to the customer.

Sample Interval Data

service_point_id	start	usage	direction
686656923	2025-04-01 07:00:00 UTC	0	delivered
686656924	2025-04-01 07:00:00 UTC	1.25	delivered
686656925	2025-04-01 07:00:00 UTC	2.888	delivered
686656926	2025-04-01 07:00:00 UTC	0.4	delivered
686656927	2025-04-01 07:00:00 UTC	0.8991	delivered
686656928	2025-04-01 07:00:00 UTC	0.4	delivered
686656929	2025-04-01 07:00:00 UTC	1.3757	delivered
686656930	2025-04-01 07:00:00 UTC	0.452	delivered
686656931	2025-04-01 07:00:00 UTC	0.5224	delivered
686656932	2025-04-01 07:00:00 UTC	0.86636	delivered
686656933	2025-04-01 07:00:00 UTC	1.281	delivered
686656934	2025-04-01 07:00:00 UTC	0.122	delivered
686656935	2025-04-01 07:00:00 UTC	1.2878	delivered
686656936	2025-04-01 07:00:00 UTC	0.119	delivered
686656937	2025-04-01 07:00:00 UTC	0.144	delivered
686656938	2025-04-01 07:00:00 UTC	0.191	delivered
686656939	2025-04-01 07:00:00 UTC	0.1936	delivered
686656940	2025-04-01 07:00:00 UTC	0.1654	delivered
686656941	2025-04-01 07:00:00 UTC	0.1488	delivered