IntroductionThis document specifies and defines files and file fields for the House Facts Open Data Standard Version:
0.2.3 Revision Date: 15 July, 2014
Summary File Descriptions
File
Names
|
Required?
|
Contains
|
feed.csv
|
Required
|
This file contains
information about the source of the data in the files in a single row
|
buildings.csv
|
Required
|
This file contains
required and optional information about all residential building under an
agency or localities regulatory authority.
|
inspections.csv
|
Required
|
This file contains
information about regulatory inspections of residential buildings by one or
more regulatory agencies.
|
violations.csv
|
Required
|
This file contains
information about regulatory violations observed or documented by regulatory
agencies.
|
building_performance.csv
|
Optional
|
This file contains
information about achievement of various voluntary and regulatory high
performance building standards.
|
building_utilities.csv
|
Optional
|
This file contains
information about building utility consumption.
|
parcels.zip
|
Optional
|
This optional file
contains municipality-wide information about the parcel or lot property
lines. The file should include six files with the same name with the following extensions .dbf, .prj, .sbn, .sbx, .shp, .shx, and .shp.xml.
|
File Requirements
Consolidated in a single ZIP file - YYYYMMDD_name.zip In individual comma-delimited text files Via an open data portal that allows, at minimum, .CSV file exports
The first line of each file must contain field names. Field names for each file are defined below under the ‘Files’ heading. All field names are case-sensitive. Field values may not contain tabs, carriage returns or new lines. Field values that categorize by type should contain a finite and standardized list of category descriptors with identical spelling, punctuation, capitalization and phrasing for all values in the same category. Field values that contain quotation marks or commas must be enclosed within quotation marks. In addition, each quotation mark in the field value must be preceded with a quotation mark. This is consistent with the manner in which Microsoft Excel outputs comma-delimited (CSV) files. For more information on the CSV file format, see http://tools.ietf.org/html/rfc4180. Field values must not contain HTML tags, comments, escape sequences, or anything else designed to break or confuse our computers. Remove any extra spaces between fields or field names. Many parsers consider the spaces to be part of the value, which may cause errors. Each line must end with a CRLF or LF linebreak character. Files should be encoded in UTF-8 to support all Unicode characters. Files that include the Unicode byte-order mark (BOM) character are acceptable. Files should be updated weekly to reflect current inspection results.
File Specifications feed.csvRequired File
Name
|
Type
|
Required
|
Description
|
feed_date
|
date
|
Yes
|
Date this feed was generated in YYYY-MM-DD format
|
feed_version
|
string
|
Yes
|
Version of the OHHS specification used to generate this
feed. For example ‘0.1’
|
feed_url
|
string
|
Yes
|
URL where House Facts Data is published.
|
municipality_name
|
string
|
Yes
|
Name of the municipality providing this feed, for example,
‘San Francisco’ or ‘Multnomah County’
|
agency_name
|
string
|
Yes
|
Name of agency providing this feed, for example, ‘Building
Department.’
|
building_id_definition
|
string
|
Yes
|
Describes how the municipality defines or creates the
variable building_id convention for defining building_id.
|
parcel_id_definition
|
string
|
Yes
|
Describes how the municipality defines or creates the
variable parcel_id
|
municipality_url
|
string
|
No
|
URL of the publishing municipality’s website
|
contact_email
|
string
|
No
|
Email address of the person to contact regarding invalid
data in this feed
|
buildings.csvRequired File
Field Name
|
Type
|
Required
|
Description
|
building_id
|
string
|
Yes
|
Building_id is a
unique alpha-numeric identifier created or assigned by a
single authoritative agency in a locale (e.g. tax collector) that
identifies each residential building inspected by any agency in locality. See
source and definition of building_id in feed.csv below.
|
parcel_id
|
string
|
No
|
Unique BLKLOT
identifier
|
facility_type
|
string
|
No
|
Type of residential
property :
Single Family -
Uncategorized
Single Family -
Attached
Single Family -
Detached
Single Family - Mobile
Home
Multifamily - Duplex
Multifamily - Townhome
Multifamily -
Condominium
Multifamily -
Apartment
Uncategorized
|
dwelling_units
|
number
|
Yes
|
Number of residential
dwelling units
|
occupancy
|
number
|
No
|
Occupancy of the
building if available
|
built_year
|
number
|
Yes
|
Year building was
constructed or rebuilt.
|
gross_floor_area
|
number
|
Yes
|
Recorded building
gross floor area (square feet)
|
heated_floor_area
|
number
|
No
|
Floor area of the
building which is heated
|
cooled_floor_area
|
number
|
No
|
Floor area of the
building which is cooled
|
lighted_floor_area
|
number
|
No
|
Floor area of the
building which is lighted
|
building_value
|
number
|
No
|
Current assessed
property value.
|
from_st
|
string
|
Yes
|
Lowest numerical value
of the street number if the building has an address range or only building
street number.
|
to_st
|
string
|
No
|
Highest numerical
value of the street number if the building has an address range.
|
street
|
string
|
Yes
|
Street name
|
predir
|
String
|
Yes
|
Field for the prefix
that precedes the street name, for example, N(orth), E(ast), S(outh) or
W(est)
|
sufdir
|
String
|
Yes
|
Field for the suffix
that follows the street name, for example, N(orth), E(ast), S(outh) or
W(est)
|
street_type
|
string
|
Yes
|
Street type (St, Ave,
Way)
|
city
|
string
|
Yes
|
City where the
property is located.
|
state
|
string
|
Yes
|
State where the
property is located. In the U.S. this should be the two-letter code for the
state
|
postal_code
|
string
|
Yes
|
Zip code or other
postal code
|
latitude
|
number
|
Yes
|
Latitude of the
residential building parcel. This field must be a valid WGS 84 latitude. For
example 37.7859547
|
longitude
|
number
|
Yes
|
Longitude of the
residential building parcel. This field must be a valid WGS 84 longitude. For
example -122.4024658
|
operator_type
|
string
|
No
|
The kind of entity
which is responsible for operating the building: Private owner;
property management; tenant; public institution; non-profit institution;
bank.
|
owner_name
|
string
|
Yes
|
Property owner. This
may be an individual or business entity.
|
owner_mailing_address
|
string
|
No
|
Mailing address for
the owner of record. For example Jane Smith 310 Polaris Way San
Francisco CA 94117
|
date_updated
|
Date
|
No
|
date that the record
was created or updated.
|
inspections.csvRequired File
Name
|
Type
|
Required
|
Description
|
inspection_id
|
string
|
Yes
|
Unique ID for
inspection; format provided by municipality
|
building_id
|
string
|
Yes
|
Unique identifier for
the residential property being inspected.
|
inspection_date
|
date
|
Yes
|
Date of the inspection
in YYYY-MM-DD format
|
inspection_address
|
string
|
Yes
|
Address at which the
inspection occurred
|
inspection_unit_number
|
string
|
No
|
Identification for
specific unit in a multi-unit building where inspection was conducted, for
example, “113” or “F.”
|
inspection_agency
|
string
|
Yes
|
Type of agency conducting
the inspection. Must be one of the following types: Health, Environment,
Building, Housing, Planning, Fire, Code Enforcement.
|
inspection_purpose
|
string
|
Yes
|
Reason for the
inspection. Must be one of the following types: permit [approval], routine
or periodic [monitoring], complaint or service request [response],
follow-up [of a previous inspection].
|
inspection_category
|
string
|
No
|
Functional category or
subject of the inspection. For example, structural, mechanical, plumbing, pest-control,
fire prevention, noise, indoor air quality, etc
|
inspection_rating
|
string
|
Yes
|
Inspection rating or
result, for example, “pass/ fail,” “satisfactory/ not-satisfactory,”
if one exists.
|
inspection_score
|
number
|
No
|
Numerical score
associated with the inspection if one exists
|
latitude
|
number
|
Yes
|
Latitude of the
residential building parcel. This field must be valid WGS 84 latitude. For
example 37.7859547
|
longitude
|
number
|
Yes
|
Longitude of the residential
building parcel. This field must be valid WGS 84 longitude. For example
-122.4024658
|
Date_updated
|
date
|
No
|
Date that the record
was updated or created.
|
Required File
Name
|
Type
|
Required
|
Description
|
violation_id
|
number
|
Yes
|
Unique identifier for the violations
|
building_id
|
string
|
Yes
|
Unique identifier for the property being inspected.
|
inspection_id
|
number
|
Yes
|
Unique identifier for the inspection
|
Inspection_agency
|
string
|
Yes
|
Type of agency issuing the violation, for example, Health,
Environment, Building, Housing, Planning, Fire, Code Enforcement.
|
Inspection_purpose
|
string
|
Yes
|
Reason for the inspection, for example, permit [approval] , routine or
periodic [monitoring], complaint [response], follow-up [of a previous
inspection].
|
violation_date
|
date
|
Yes
|
Date that the violation was recorded in YYYY-MM-DD
format.
|
violation_status
|
string
|
Yes
|
Violation status: Open or Closed.
|
violation_address
|
string
|
Yes
|
Address where violation observed.
|
violation_unit_number
|
string
|
No
|
Identification for specific unit in a multi-unit building
where violation occurred, for example, “113” or “F.”
|
violation_date_closed
|
date
|
Yes
|
Date that the violation was closed in YYYY-MM-DD format.
|
violation_reason_closed
|
string
|
No
|
Reason
that the violation was closed (e.g. violation corrected by responsible party)
|
violation_category
|
string
|
Yes
|
Violation category. Must be one of the categories in the
HFDS list of violation categories.
|
violation_type
|
string
|
Yes
|
Violation type (bedbugs, mold, etc)
|
violation_code
|
string
|
no
|
The legal authority under which a violation is issued, for
example, a section of the housing code.
|
violation_severity
|
string
|
No
|
May be one of the following categories: high (imminently
harmful to health and requires rapid correction) and low (nuisance with
correction over a reasonable period of time)
|
latitude
|
number
|
Yes
|
Latitude of the residential building parcel. This field
must be a valid WGS 84 latitude. For example 37.7859547
|
longitude
|
number
|
Yes
|
Longitude of the residential building parcel. This field
must be a valid WGS 84 longitude. For example -122.4024658
|
Date_updated
|
Date
|
No
|
Date the violation record was created or updated.
|
building_performance_standards.csv(optional file)
This
optional file provides information on building performance certifications
achieved for the residential building. Building performance can be rated with regards
to energy efficiency, air quality, or overall sustainability performance.
A single building may have multiple performance certifications
represented as multiple file records.
building_utilities.csv
(optional file)
This optional file provides for reporting of summary
building-level data on environmental resources consumption (e.g. utilities).
Each building would have a separate record for each utility type: water,
sewage, electricity, natural gas, heating oil, landfill refuse, recycled
refuse, etc. Data sources may include: government agencies which require
reporting of utility and energy efficiency data; utilities; public data sets
(e.g. DOE Building Performance Database); building owners. This standard is
intended to be compatible with the US DOE Building Energy Data Exchange
Specification.
field name
|
data type
|
required
|
description
|
building_id
|
string
|
yes
|
|
parcel_id
|
string
|
yes
|
|
building_address
|
string
|
yes
|
|
utility_type
|
string
|
yes
|
May be any one of the
following types: Water, sewage, electricity, natural gas, heating oil,
landfill refuse, recycled refuse, etc.
|
utility_data_source
|
string
|
yes
|
Source of utility data
(e.g., utility provider, municipality, building owner, EPA portolio manager,
private energy benchmarking software, etc)
|
utility_measure
|
string
|
yes
|
*Standardize units for
this field include: kwh (electricity), therms (natural gas), gallons (water),
|
utility_report_date
|
date
|
yes
|
Date data provided by
source
|
utility_report_period
|
number
|
yes
|
Number of months of
utility data
|
monthly_utility_use
|
number
|
yes
|
Average utility
consumption per unit
|
parcels.zip(optional file)
Name | Type | Required | Description | Shape | geometry | Yes | This
field contains data that describes the boundaries of the lot. It is
generated automatically when the shapefile is created and will display a
type of polygon or multipolygon. | parcel_id | string | Yes | Local identifier for all parcel footprint that the building sits on. | building_id | string | Yes | Unique identifier for the residential building. Can correspond to more than one parcel_id or an address range |
Standard Violation Categories
This table provides a table of standard violation categories for the violation categories field in violations.csv.
Violation Category | Violation Category Examples | Animals and Pests | Cockroaches; rats; mice; bedbugs; racoons | Vegetation | Overgrown vegetation, landslide | Refuse | Refuse accumulation; dumping; spoiled food | Sanitation | Unsanitary floors or walls; non-functioning sewage system | Radiation Hazard | Radon | Air Pollutants and Odors | Nuisance odors; smoking in common areas | Biological Hazard | Medical waste; Contaminated Needles, mold/mildew | Chemical Hazards | Lead hazard; asbestos hazard | Noise | Interior noise violation; exterior noise violation | Indoor Climate | Inadequate heat or ventilation | Plumbing | No running water; inoperable toilet | Electrical | Exposed electrical hazards; excess electrical loads | Fire Hazards and Prevention | Non-functioning smoke detector; heat source near combustible material | Building Security | Inadequate exterior lighting | Building Structure | Water or moisture intrusion; structural hazard; | Planning or Zoning | Unpermitted use; violations of conditions of use | Abandon, Boarded or Substandard Building | Abandoned Building; Blighted Building; Dilapidated Housing | No Permit | No permit for electrical, gas, construction, plumbing ect | Water Hazard | Storm Water; Water Leak; Sewer Leak | Gas Hazard | Gas Leak, Illegal Gas Appliance | Other | Other |
 House Facts Data Standard is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.
|