Targeting 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)
• 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	FLOAT64	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	FLOAT64	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		Preferred	Yes	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)

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)
• 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	FLOAT64	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.