Building Inspector is not compatible with Internet Explorer 9 or earlier. Please download a more recent version or try another browser.

FREE polygons for fun (and profit)!

Why bother classifying thousands of building footprints if you can't get your hands on the resulting data, right? Well, fear not! Building Inspector has been built from the beginning to be open. As volunteers (like yourself) inspect polygons, the API endpoints below get updated (on a daily basis) to reflect the latest data (both the perfect and the imperfect bits).

Read below for some basic documentation. If you need more detailed information, check out the source code on GitHub or drop us a line at buildinginspector@nypl.org or at our Twitter account.

Contents

Some basics

In order to understand the API endpoints you first need to understand some basic Building Inspector concepts:

GeoJSON
Everything in this API is returned as a GeoJSON string. You can easily verify/visualize the output using GeoJSONLint or GeoJSON.io.
Polygon
Polygons are the building blocks of the Building Inspector (har har). Polygons are possible building footprints that have been identified by the NYPL Map Vectorizer. The vectorizer produces some extra metadata that you can safely ignore (and may or may not be included in the API).
Maps: Atlases and Sheets
The maps in Building Inspector come from historical atlases of New York City which, rather than being one big map, are split into pages (because they're in books). Polygons come from atlas sheets which are scanned one at a time and then geo-rectified via the NYPL Map Warper. The vectorizer goes through each map sheet and extracts buildings as best it can. And it's not good enough; that's why this site exists: to validate and improve the output of the vectorizer. Each polygon is associated to a sheet_id.
Task
The type of inspection being made to a polygon. Right now there are five tasks: geometry, polygonfix, address, color and toponym.
Consensus
In order to create reliable results, we present the same task several times to multiple users. We then run a process to make an effective decision of which value is the correct one based on an overwhelming user agreement. This is what we call “consensus”. The mechanism for consensus varies from task to task. Some of the endpoints in this API only return consensus values.
Geometry task
This is the main/first task for any polygon. You are inspecting a polygon to find out if its shape: matches a building (value: YES), matches part of a building but needs fixing (value: FIX) or does not match a building at all (value: NO).
Polygonfix task
Polygons that are classified as FIX get sent to this task. Its purpose is to create new geometry(ies) that will better match the building(s). The resulting value is(are) GeoJSON geometry(ies).
Address task
Polygons that are classified as YES get sent to this task. Its purpose is to find the address numbers (if any) associated to a given polygon. The resulting value is an array of address numbers with their latitude and longitude values or NONE.
Colors task
Polygons that are classified as YES also get sent to this task. Its purpose is to find the colors present in a building. The resulting value is a comma-separated string with any of the colors. Current possible colors are pink, blue, yellow, green and gray.
Toponym task
Toponym is the fancy word for place name. Basically the text on the map. This task is applied to sheets instead of polygons since many placenames do not belong to a building (parks, cemeteries).

Note: Not all tasks and consensus types have been implemented. If you definitely have to have those polygons (and we can't blame you) contact us at our Twitter account and we'll hook you up.

Pagination

All results are paginated by batches of 500 results (you can always get fewer). You can append /page/:page to any endpoint to request the specific page. If you do not request a specific page, the first one will be returned. If you attempt to access a page beyond the last page you'll be returned an empty GeoJSON result.

Polygons

This section covers endpoints for building footprints (polygons).

Geometry

GET /api/polygons/geometry/{value}

Returns the list of polygons that have a consensus of {value} (yes, no, fix). If no value is provided, all polygons will be returned regardless of their consensus.

Example response
        
{
  "message": "List for informative purposes only.",
  "polygon_count": "2",
  "page": 1,
  "per_page": 500,
  "total_pages": 1,
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "consensus": "yes",
        "id": 73000,
        "dn": 1002010,
        "sheet_id": 138
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-73.9981514825787, 40.75699146852938],
            [-73.99820209636397, 40.757014472045185],
            [-73.99816666671428, 40.75706431296879],
            [-73.99809833810419, 40.757035558594346],
            [-73.9981312370646, 40.75698955156937],
            [-73.99813629844313, 40.75698571764918],
            [-73.9981514825787, 40.75699146852938]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "consensus": "yes",
        "id": 73001,
        "dn": 1005025,
        "sheet_id": 138
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-73.9976238409442, 40.75697150401845],
            [-73.99763605041814, 40.75696082476952],
            [-73.99764622497976, 40.75696349458192],
            [-73.99778052919307, 40.75702223042746],
            [-73.99778256410538, 40.75703023985692],
            [-73.99775204042055, 40.75707028698976],
            [-73.9976055267333, 40.75700621156564],
            [-73.99760349182097, 40.75699820213328],
            [-73.9976238409442, 40.75697150401845]
          ]
        ]
      }
    }
  ]
}        
    

Color

GET /api/polygons/color/{value}

Returns the list of polygons that were marked as "yes" in the geometry task and have a consensus of {value} (pink, blue, yellow, green, gray or a combination of those in alphabetical order).

Example response
        
{
  "message": "List for informative purposes only.",
  "polygon_count": "2",
  "page": 1,
  "per_page": 500,
  "total_pages": 1,
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "consensus": "yellow",
        "id": 73000,
        "dn": 1002010,
        "sheet_id": 138
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-73.9981514825787, 40.75699146852938],
            [-73.99820209636397, 40.757014472045185],
            [-73.99816666671428, 40.75706431296879],
            [-73.99809833810419, 40.757035558594346],
            [-73.9981312370646, 40.75698955156937],
            [-73.99813629844313, 40.75698571764918],
            [-73.9981514825787, 40.75699146852938]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "consensus": "pink",
        "id": 73001,
        "dn": 1005025,
        "sheet_id": 138
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-73.9976238409442, 40.75697150401845],
            [-73.99763605041814, 40.75696082476952],
            [-73.99764622497976, 40.75696349458192],
            [-73.99778052919307, 40.75702223042746],
            [-73.99778256410538, 40.75703023985692],
            [-73.99775204042055, 40.75707028698976],
            [-73.9976055267333, 40.75700621156564],
            [-73.99760349182097, 40.75699820213328],
            [-73.9976238409442, 40.75697150401845]
          ]
        ]
      }
    }
  ]
}        
    

Address

GET /api/polygons/address

Returns the list of polygons that were marked as "yes" in the geometry task and have a consensus of either NONE (buildings that do not have an address associated) or a JSON structure with an array of address numbers each with: latitude, longitude, flag_value (the address number), votes (number of inspectors voting for this value), total_votes (total inspectors for this or other value), and flaggable_id (polygon_id in this case). Polygons can have none or many addresses.

Example response
        
{
  "message": "List for informative purposes only. This is not a definitive list. This URL may be changed at any time without prior notice.",
  "polygon_count": "64086",
  "page": 1,
  "per_page": 500,
  "total_pages": 129,
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": 93270,
        "dn": 309909,
        "sheet_id": 186,
        "consensus": [
          {
            "latitude": 40.7276083810125,
            "longitude": -74.0093544870615,
            "flag_value": "117",
            "votes": 4,
            "total_votes": 4,
            "flaggable_id": 93270
          }
        ]
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-74.00933215733832, 40.72762581318789],
            [-74.0093859620873, 40.727630105219944],
            [-74.00936897111393, 40.727720237829026],
            [-74.0093066708783, 40.72771379978957],
            [-74.00932083002276, 40.72762366717176],
            [-74.00933215733832, 40.72762581318789]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 77181,
        "dn": 376944,
        "sheet_id": 147,
        "consensus": "NONE"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-73.98278569092857, 40.76394745989852],
            [-73.98282496740708, 40.76396445889229],
            [-73.98276044176382, 40.76405157866709],
            [-73.98275483083829, 40.76405370353822],
            [-73.98271274889703, 40.76403670456728],
            [-73.98271274889703, 40.76402820508019],
            [-73.98277446907755, 40.763945335024],
            [-73.98278569092857, 40.76394745989852]
          ]
        ]
      }
    }
  ]
}        
    

Consolidated polygons

GET /api/consolidated

Returns the consolidated geometry (polygon shape) list of polygons that either have consensus of YES (no fix required) or were classified as FIX and were subsequently fixed by inspectors. In the latter case, the original raw geometry is replaced with the consensus geometry (this is repeated in the consensus property for the polygon). It also includes the address consensus for that polygon, if any: the geometry type for these polygons is returned as GeometryCollection with each address Point being sent with the polygon's Polygon geometry and the address Properties being returned as an array in the consensus_address property of the polygon.

Example response
        
{
  "message": "List for informative purposes only. This is not a definitive list. This URL may be changed at any time without prior notice.",
  "polygon_count": "72689",
  "page": 1,
  "per_page": 500,
  "total_pages": 146,
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": 73000,
        "dn": 1002010,
        "sheet_id": 138,
        "consensus": "yes",
        "fixed": false,
        "map_id": "7099",
        "consensus_color": "yellow",
        "consensus_address": "NONE"
      },
      "geometry": {
        "type": "GeometryCollection",
        "geometries": [
          {
            "type": "Polygon",
            "coordinates": [
              [
                [-73.9981514825787, 40.75699146852938],
                [-73.99820209636397, 40.757014472045185],
                [-73.99816666671428, 40.75706431296879],
                [-73.99809833810419, 40.757035558594346],
                [-73.9981312370646, 40.75698955156937],
                [-73.99813629844313, 40.75698571764918],
                [-73.9981514825787, 40.75699146852938]
              ]
            ]
          }
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 73001,
        "dn": 1005025,
        "sheet_id": 138,
        "consensus": "yes",
        "fixed": false,
        "map_id": "7099",
        "consensus_color": "pink",
        "consensus_address": [
          {
            "votes": 3,
            "total_votes": 3,
            "flag_value": "445"
          }
        ]
      },
      "geometry": {
        "type": "GeometryCollection",
        "geometries": [
          {
            "type": "Polygon",
            "coordinates": [
              [
                [-73.9976238409442, 40.75697150401845],
                [-73.99763605041814, 40.75696082476952],
                [-73.99764622497976, 40.75696349458192],
                [-73.99778052919307, 40.75702223042746],
                [-73.99778256410538, 40.75703023985692],
                [-73.99775204042055, 40.75707028698976],
                [-73.9976055267333, 40.75700621156564],
                [-73.99760349182097, 40.75699820213328],
                [-73.9976238409442, 40.75697150401845]
              ]
            ]
          },
          {
            "type": "Point",
            "coordinates": [-73.99760551750667, 40.756970718269]
          }
        ]
      }
    }
  ]
}        
    

Sheets

This section covers endpoints for data related to sheets.

List

GET /api/sheets

Returns the list of sheets with their bounding box as a polygon and its parent layer information.

Example response
        
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "bbox": "-74.005129,40.6844534,-73.9962649,40.6921512",
        "created_at": "2013-11-19T21:50:44Z",
        "id": 268,
        "layer": {
            "bbox": "-74.03,40.63,-73.94,40.71",
            "created_at": "2015-04-13T18:48:48Z",
            "description": "Maps of the city of Brooklyn",
            "external_id": 860,
            "id": 860,
            "name": "Brooklyn",
            "tilejson": "https://s3.amazonaws.com/maptiles.nypl.org/860/860spec.json",
            "tileset_type": "tms",
            "updated_at": "2015-04-13T18:48:48Z",
            "year": "1855"

        },
        "layer_id": 860,
        "map_id": "7240",
        "status": "done",
        "updated_at": "2013-11-19T21:50:44Z"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-74.005129, 40.6844534],
            [-74.005129, 40.6921512],
            [-73.9962649, 40.6921512],
            [-73.9962649, 40.6844534],
            [-74.005129, 40.6844534]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "bbox": "-73.9910573,40.7729807,-73.9808465,40.781313",
        "created_at": "2013-10-18T15:27:46Z",
        "id": 161,
        "layer": {
            "bbox": "-74.04,40.69,-73.93,40.77",
            "created_at": "2015-04-13T18:48:43Z",
            "description": "Maps of the city of New York",
            "external_id": 859,
            "id": 859,
            "name": "Manhattan",
            "tilejson": "https://s3.amazonaws.com/maptiles.nypl.org/859/859spec.json",
            "tileset_type": "tms",
            "updated_at": "2015-04-13T18:48:43Z",
            "year": "1857"
        },
        "layer_id": 859,
        "map_id": "7122",
        "status": "done",
        "updated_at": "2013-10-18T15:27:46Z"
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-73.9910573, 40.7729807],
            [-73.9910573, 40.781313],
            [-73.9808465, 40.781313],
            [-73.9808465, 40.7729807],
            [-73.9910573, 40.7729807]
          ]
        ]
      }
    }
  ]
}        
    

Polygons

GET /api/sheets/{id}/polygons

Returns the list of raw (before any inspection) polygons for a sheet with ID {id}.

Example response
        
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "consensus": null,
        "id": 115093,
        "dn": 136023,
        "sheet_id": 219
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-74.0071522085753, 40.73576686668677],
            [-74.00717989858511, 40.73576686668677],
            [-74.00721451109736, 40.73589275539532],
            [-74.00714874732408, 40.7359006234317],
            [-74.00714182482163, 40.73589275539532],
            [-74.00711413481184, 40.73577473473803],
            [-74.0071522085753, 40.73576686668677]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "consensus": null,
        "id": 115311,
        "dn": 358460,
        "sheet_id": 219
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-74.00545790306707, 40.73489464280556],
            [-74.00547602169983, 40.73489199081001],
            [-74.005498157153, 40.73498241159547],
            [-74.00543161226139, 40.73499218213892],
            [-74.00542825434526, 40.73498853932166],
            [-74.00540923016135, 40.73490270720948],
            [-74.00545790306707, 40.73489464280556]
          ]
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "consensus": null,
        "id": 115204,
        "dn": 247288,
        "sheet_id": 219
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-74.00629287248056, 40.7353050363298],
            [-74.00630477235585, 40.735308159882706],
            [-74.00630001240573, 40.735348766057236],
            [-74.00626074281725, 40.735347204281744],
            [-74.00620243342827, 40.735336271852326],
            [-74.006210763341, 40.735322215869004],
            [-74.00623694306664, 40.73531909231675],
            [-74.0062631227923, 40.73530347455329],
            [-74.00629287248056, 40.7353050363298]
          ]
        ]
      }
    }
  ]
}        
    

Place names

GET /api/sheets/{id}/toponyms

Returns the place name consensus (so far) associated with a sheet with ID {id}.

Example response
        
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "consensus": "Rigging Loft"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -73.987003415823,40.704169027369
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "consensus": "Pattern Shop"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -73.988353908062,40.70355766475467
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "consensus": "Office"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -73.98514822125433,40.703639338245004
        ]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "consensus": "Casting Shop"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [
          -73.98815944790833,40.70215801635367
        ]
      }
    }
  ]
}        
    

History

GET /api/sheets/{id}/history

Returns the all the flags associated with a sheet with ID {id} and its child polygons sorted by creation date.

Example response
        
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": 5460,
        "flaggable_id": 115148,
        "flaggable_type": "Polygon",
        "flag_type": "geometry",
        "session_id": 1,
        "flag_value": "yes"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-74.009614466801, 40.733523404832]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 5462,
        "flaggable_id": 115650,
        "flaggable_type": "Polygon",
        "flag_type": "geometry",
        "session_id": 1,
        "flag_value": "no"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-74.009614466801, 40.733523404832]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 5464,
        "flaggable_id": 115379,
        "flaggable_type": "Polygon",
        "flag_type": "geometry",
        "session_id": 1,
        "flag_value": "fix"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-74.005486621588, 40.734717823179]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 515374,
        "flaggable_id": 115327,
        "flaggable_type": "Polygon",
        "flag_type": "color",
        "session_id": 2,
        "flag_value": "pink"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-74.008614570398, 40.73486559075]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 475918,
        "flaggable_id": 115531,
        "flaggable_type": "Polygon",
        "flag_type": "address",
        "session_id": 3,
        "flag_value": "130"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-74.007593616843, 40.734154657598]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 1128326,
        "flaggable_id": 219,
        "flaggable_type": "Sheet",
        "session_id": 4,
        "flag_value": "Smelter of Metals"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-74.009640812874, 40.735820214571]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 483279,
        "flaggable_id": 115471,
        "flaggable_type": "Polygon",
        "flag_type": "polygonfix",
        "session_id": 5
      },
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-74.00954919204457, 40.734321831207836],
            [-74.009715244174, 40.73429032227927],
            [-74.00970585644245, 40.73435637614378],
            [-74.00956369936465, 40.73437568418409],
            [-74.00954919204457, 40.734321831207836]
          ]
        ]
      }
    }
  ]
}        
    

History for task

GET /api/sheets/{id}/history/{task}

Returns the all the flags associated with a sheet with ID {id} and task {task} and its child polygons sorted by creation date.

Example response
        
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "id": 5460,
        "flaggable_id": 115148,
        "flaggable_type": "Polygon",
        "flag_type": "geometry",
        "session_id": 1,
        "flag_value": "yes"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-74.009614466801, 40.733523404832]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 5462,
        "flaggable_id": 115650,
        "flaggable_type": "Polygon",
        "flag_type": "geometry",
        "session_id": 1,
        "flag_value": "no"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-74.009614466801, 40.733523404832]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "id": 5464,
        "flaggable_id": 115379,
        "flaggable_type": "Polygon",
        "flag_type": "geometry",
        "session_id": 1,
        "flag_value": "fix"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [-74.005486621588, 40.734717823179]
      }
    }
  ]
}        
    

Place names (toponyms)

GET /api/toponyms

Returns the all place names with consensus. Will take a few seconds to retrieve.

Example response
        
{
  "message": "List for informative purposes only.",
  "toponym_count": "2",
  "type": "FeatureCollection",
  "features": [
    {
      "type":"Feature",
      "properties": {
          "consensus":"Bonded Warehouse",
          "sheet_id":170
      },
    "geometry": {
        "type":"Point",
        "coordinates":[-74.01512817911767,40.7068985672498]
      }
    },
    {
      "type":"Feature",
      "properties": {
          "consensus":"Potash Inspection",
          "sheet_id":170
      },
      "geometry": {
        "type":"Point",
        "coordinates":[-74.01503990803452,40.707777540425006]
      }
    }
  ]
}