/
help.html
103 lines (90 loc) · 16.9 KB
/
help.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
<!DOCTYPE html>
<html>
<head>
<title>NYC Address and BIN Search</title>
<meta charset='utf-8'/>
<link rel="stylesheet" type="text/css" href="help.css">
<style>
.markdown-body {
box-sizing: border-box;
min-width: 200px;
max-width: 980px;
margin: 0 auto;
padding: 45px;
}
</style>
</head>
<body>
<article class="markdown-body">
<h1 id="nyc-address-and-bin-search"><a href="javascript:void(0);" onclick="window.history.back()"><</a> NYC Address and BIN Search</h1>
<p><em>Project repository at <a href="https://github.com/jmapb/nycaabs/">https://github.com/jmapb/nycaabs/</a></em></p>
<p>Nycaabs searches New York City's open data APIs for building information by address, BIN (building identification number), or latitude/longitude coordinates.</p>
<p>This tool aims to help maintain NYC's <a href="https://www.openstreetmap.org/#map=12/40.6951/-73.9758">OpenStreetMap</a> data, in particular building footprints, heights, BINs, and addresses.</p>
<p>Nycaabs search can be initiated from the search box at the top of the page, or by supplying a "search=" URL parameter. Details of the API queries are logged in an expandable textarea below the search box. Results will be displayed below that, some as text and some in the building info table at the bottom left. If a building footprint is found, it will be highlighted on the slippy map at the top right.</p>
<h2 id="bin-search">BIN search</h2>
<p>Specify a valid 7-digit BIN in the search box or with a "search=" url parameter. Nycaabs will pull from the following open data sources:</p>
<ul>
<li><strong><a href="https://data.cityofnewyork.us/Housing-Development/Building-Footprints/nqwf-w8eh">Building Footprints</a></strong> for building status, type, height, and footprint geometry.</li><li><strong><a href="https://data.cityofnewyork.us/Housing-Development/DOB-Job-Application-Filings/ic3t-wcy2">DOB Job Application Filings</a></strong> for building info recorded by the NYC Department of Buildings for construction and alteration permits.</li><li><strong><a href="https://data.cityofnewyork.us/Housing-Development/DOB-NOW-Build-Approved-Permits/rbx6-tga4">DOB NOW: Build – Approved Permits</a></strong> for building info recorded through the NYC Department of Buildings "DOB NOW" system.</li><li><strong><a href="https://data.cityofnewyork.us/Housing-Development/Buildings-Subject-to-HPD-Jurisdiction/kj4p-ruqc">Buildings Subject to HPD Jurisdiction</a></strong> to link to a building's Department of Housing and Development profile, if available.</li></ul>
<p>Results from these searches will populate the <strong>Address</strong>, <strong>BBL</strong>, <strong>HPD ID</strong> and <strong>Building Class</strong> fields, and the building info table at the bottom left. Note that for some properties, the address returned from a BIN search might not be the observed on-the-ground address – or might be one of several.</p>
<p>If a building footprint is found for this BIN, it will be displayed and zoomed on the slippy map at the top right. If no footprint is found but location coordinates are, the location will be marked with a pin and zoomed.</p>
<h2 id="address-search">Address search</h2>
<p>Specify an NYC address in the search box or with a "search=" url parameter. Nycaabs will use the <strong><a href="https://geosearch.planninglabs.nyc">NYC Geosearch API</a></strong> to find the normalized address form, BIN, and BBL. NYC Geosearch will often be able to correctly identify the address even with imprecise search text – eg, missing a borough name or part of the street name. It may also sometimes return results far from the intended location. Always check that the address returned actually matches the intended target, and retry with more explicit search terms (eg full street name and borough) if necessary.</p>
<p>If the desired address can't be found, it might not exist – or it might be too new. Consider trying the address search with GOAT (see below) to find a BIN, and then searching that BIN on Nycaabs.</p>
<p>If the BIN returned is valid, Nycaabs will proceed with a BIN search as described above, looking for a footprint and populating the building info table.</p>
<h2 id="coordinate-search">Coordinate search</h2>
<p>Specify coordinates in latitude, longitude order, in the search box or with a "search=" url parameter. Nycaabs will query the <strong><a href="https://data.cityofnewyork.us/Housing-Development/Building-Footprints/nqwf-w8eh">Building Footprints</a></strong> dataset for a footprint that matches the coordinates. If found, the footprint will be displayed on the slippy map at the top right.</p>
<p>This search may fail if the Building Footprints dataset hasn't yet been updated with the building in question. Also note that the coordinates must actually fall inside the building -- a search that lands in a building courtyard will not work.</p>
<p>If a footprint result includes a valid BIN, Nycaabs will proceed with a BIN search as described above, populating the building info table.</p>
<h2 id="using-external-address-info-links">Using external address info links</h2>
<p>If an address is successfully found, links will be generated to query the normalized address using external resources.</p>
<h3 id="search-address-bis">Search Address @ BIS</h3>
<p>This link will query the address using a mode 1 property search on NYC Department of Buildings' "Building Information Search" tool (BIS for short, <a href="https://a810-bisweb.nyc.gov/bisweb/bispi00.jsp">https://a810-bisweb.nyc.gov/bisweb/bispi00.jsp</a>). If successful, this will load BIS's "Property Profile Overview" page for the address in question, which is the starting point to access the DOB's records for this property.</p>
<p>BIS gives access to a wealth of information about NYC properties and buildings, but is subject to frequent timeouts and strict usage quotas. The drill-down search interface means that finding building info will usually take several clicks, and the chance of failure increases with each page load.</p>
<p>Avoiding this frustration is one of the primary purposes of Nycaabs, which attempts to retrieve all available relevant data with a single query. But if an address search at BIS is still necessary, it's recommended to use the <strong>Search Address @ BIS</strong> link from Nycaabs rather than loading BIS's own search form, because one fewer BIS page load will increase the odds of success.</p>
<h3 id="search-address-goat">Search Address @ GOAT</h3>
<p>This link will query the address using "Function 1A" of the NYC Department of Planning's "Geographic Online Address Translator" tool (GOAT for short, <a href="https://a030-goat.nyc.gov/goat/">https://a030-goat.nyc.gov/goat/</a>). This will show detailed property-level info as recorded by the Department of Planning's "Geosupport" system.</p>
<p>GOAT is the <em>only</em> online source for fully up-to-date address and BIN info. Other address search tools, including the NYC Geosearch API that Nycaabs uses, are populated from the Department of Planning's "Property Address Directory" (PAD for short) which is updated quarterly. GOAT uses the "Transitional PAD" file (TPAD for short) for more current address data. Searching GOAT by address might therefore reveal a correct BIN when the same address search in Nycaabs returns an incorrect or invalid one. A Nycaabs search on that BIN might then return accurate up-to-date building info.</p>
<p>GOAT is also the only easy way to see every possible address, with address type classification, for a given BIN or lot. Many small lots have only a single address, while large complex lots may have multiple address ranges on multiple streets. (Many of these addresses don't exist on the ground, so are not valid data for OpenStreetMap.)</p>
<p>GOAT includes a map highlighting the property location, which is based on OpenStreetMap (via <a href="https://openmaptiles.org/">OpenMapTiles</a>) – one of the many NYC projects featuring OSM data. Unfortunately the Department of Planning has not kept this map up-to-date; the render shown is several years old.</p>
<h2 id="using-external-bin-info-links">Using external BIN info links</h2>
<p>These links will query external tools using the current BIN. Note that they won't be generated if an address search returned an invalid BIN.</p>
<h3 id="property-profile-bis">Property Profile @ BIS</h3>
<p>Similar to the <strong>Search Address @ BIS</strong>, and will generally load the same "Property Profile Overview" info by using a BIS mode 3 property search on the BIN in question.</p>
<h3 id="search-bin-goat">Search BIN @ GOAT</h3>
<p>Similar to the <strong>Search Address @ GOAT</strong>, and will load property data by using GOAT's "Function BN" search on the BIN in question. </p>
<h3 id="search-bin-overpass-turbo">Search BIN @ Overpass Turbo</h3>
<p>This link will query the OpenStreetMap tool <strong>Overpass Turbo</strong> (<a href="https://overpass-turbo.eu/">https://overpass-turbo.eu/</a>) for this BIN. Any OSM element in NYC with a <a href="https://wiki.openstreetmap.org/wiki/Key:nycdoitt:bin">nycdoitt:bin</a> tag containing the BIN in question will be found.</p>
<h2 id="using-external-bbl-info-links">Using external BBL info links</h2>
<p>If the search returns a valid Borough/Block/Lot code (which specifies a piece of real estate, whereas a BIN specifies a structure), the following external links can be used:</p>
<h3 id="browse-block-bis">Browse Block @ BIS</h3>
<p>This BIS search mode displays all BINs in the specified block. Blocks with many small buildings may have multiple pages of results. They are sorted by lot number and shown with associated addresses that may or may not match the on-the-ground addresses. The typical NYC block is a rectangle bounded by four streets, so expect to see more than one street name in the addresses.</p>
<p>Also listed are any obsolete BINs that the block previously contained, presumably demolished and often replaced by new construction with fresh BINs.</p>
<p>BIS's block-level info is often more current than other sources, so browsing this list is sometimes a better way to find a new BIN than searching by address. (The BIN, if found, can then be used for a Nycaabs BIN search.)</p>
<h3 id="browse-bbl-bis">Browse BBL @ BIS</h3>
<p>This is similar to the <strong>Browse Block</strong> search but limited to only the lot containing the BIN from the Nycaabs search. If that lot has other associated BINs they will be listed, but often the only BIN returned is the one from the original search.</p>
<h3 id="view-bbl-zola">View BBL @ ZoLa</h3>
<p>ZoLa ("Zoning and Landuse Application") is a tool from the NYC Department of Planning for researching and visualizing tax lots, zoning, ownership, political boundaries, historical aerial imagery, and many other data overlays. The ZoLa web app sometimes takes a while to load, and may appear blank for several seconds.</p>
<p>Like GOAT's, ZoLa's basemap and building footprints are OSM-based but several years old. ZoLa also offers a 3D map view, featuring the same stale data.</p>
<h2 id="using-building-footprints">Using building footprints</h2>
<p>If the BIN searched (or the BIN found from an address search) appears in NYC's <strong>Building Footprints</strong> dataset, the footprint will be shown on the slippy map and data fields will be written at the top of the building info table: the feature type (usually "building" or sometimes "garage"), the approximate year of construction, status and status date, and hopefully roof height.</p>
<p>Next to the table, links will be generated to download the footprint in OpenStreetMap XML format or send it directly to JOSM. (Note that these exported footprints do not include address fields – NYC has too many multi-address buildings to make this viable.)</p>
<p>The quality of NYC's footprints is generally very good, but there are occasional exceptions that are poorly drawn or completely erroneous. Confirm footprints with survey, aerial imagery, and street-level imagery. When importing footprints as building ways in OSM, pay attention to how the neighboring buildings interact and try to fix incorrect gaps and overlaps.</p>
<p>Also, despite frequent updates, many newer buildings are missing from the <strong>Building Footprint</strong> database. A recycled BIN will often show an obsolete footprint from the previous structure, while a new BIN may have no footprint at all. (When a Nycaabs search does <em>not</em> return a footprint but <em>does</em> return coordinates, the slippy map will zoom and drop a pin at that location.)</p>
<h2 id="using-dob-job-data">Using DOB job data</h2>
<p>Next in the building info table will be any DOB job numbers for the BIN, with job work type, status, date, and height. The heights listed with the jobs are often more accurate than the footprint's height, when there's a discrepancy.</p>
<p>The DOB Job numbers are also key for retrieving additional info from the BIS app without going through BIS's own search forms. Follow the <strong>Job Details @ BIS</strong> and <strong>Zoning Documents @ BIS</strong> links for quick access to building data and diagrams. The building zoning diagrams, if available, will usually have the most accurate building height value and will show the details of complex buildings, which can aid in 3D mapping. (When a BIN returns multiple job numbers, Nycaabs attempts to sort them so the top entry will correspond to the current active job in BIS, so the topmost links are usually a good place to start.)</p>
<p>Under the DOB Jobs may be an additional list of DOB NOW Jobs. DOB NOW (<a href="https://a810-dobnow.nyc.gov">https://a810-dobnow.nyc.gov</a>) is a new building info portal, with a distinct job number system, planned as a replacement for BIS. The DOB NOW data available in Nycaabs is usually not critical for OSM mapping, but in rare cases the building height may be available here but not elsewhere.</p>
<p>The DOB NOW application itself may offer a wealth of building information and documents, including (occasionally) zoning diagrams useful for building mapping. Unfortunately it does not support deep linking, but Nycaabs features a link that will copy the current BIN into the clipboard before opening the DOB NOW search page.</p>
<h2 id="slippy-map-functions">Slippy Map functions</h2>
<p>The slippy map supports several location-based functions available from the right-click context menu:</p>
<ul>
<li><strong>Search Here</strong>: Initiate Nycaabs coordinate search</li><li><strong>View at OSM</strong>: Open OpenStreetMap at this location</li><li><strong>Feature query at OSM</strong>: OSM's "Query features" function</li><li><strong>Reverse geocode at OSM</strong>: OSM's "Show address" function</li><li><strong>Reverse geocode at Nominatim</strong>: Query these coordinates at <a href="https://wiki.openstreetmap.org/wiki/Nominatim">https://wiki.openstreetmap.org/wiki/Nominatim</a> </li><li><strong>Edit at OSM (iD)</strong>: Edit at these coordinates in <a href="https://wiki.openstreetmap.org/wiki/iD">https://wiki.openstreetmap.org/wiki/iD</a> (or whatever editor currently resides at the <a href="https://www.openstreetmap.org/edit">https://www.openstreetmap.org/edit</a> url).</li><li><strong>Edit in Rapid</strong>: Edit at these coordinates in <a href="https://rapideditor.org">https://rapideditor.org</a>.</li><li><strong>Edit in JOSM</strong>: Edit at these coordinates in <a href="https://www.openstreetmap.org/JOSM">https://www.openstreetmap.org/JOSM</a>.</li><li><strong>Cyclomedia imagery</strong>: View street-level imagery from Cyclomedia. Note that this imagery is <strong>not</strong> licensed as a data source for OSM, so is for reference purposes only.</li><li><strong>Bing Streetside imagery</strong>: View street-level imagery from Bing Maps. This imagery is licensed as a data source for OSM, but the photography is several years old so may be of limited use.</li></ul>
<h2 id="examining-the-search-log">Examining the search log</h2>
<p>Details of the API queries that Nycaabs uses, including the exact urls and summaries of responses, are written to the small textbox underneath the search box. Expanding this box and viewing the logs may help clarify some of Nycaabs' functionality and behavior.</p>
<h2 id="crediting-data-sources">Crediting data sources</h2>
<p>Nycaabs itself is not a data source, but an aggregator. Best practice is to credit the underlying data sources (eg "NYC footprints" or "NYC DOB") along with any imagery used.</p>
<h2 id="reporting-issues">Reporting issues</h2>
<p>Issues with Nycaabs can be reported at <a href="https://github.com/jmapb/nycaabs/issues">https://github.com/jmapb/nycaabs/issues</a>. It's also possible to send a message via OSM at <a href="https://www.openstreetmap.org/user/jmapb">https://www.openstreetmap.org/user/jmapb</a>.</p>
</article>
</body>
</html>