API

Access over 5 million records thru our REST style APIs.

Introduction

Blocks And Lots publishes a set of REST style search APIs that can be accessed by most programming languages such as JavaScript, PHP, Ruby, .NET, etc. The data is returned in XML, JSON or CSV formats. These APIs allow developers to find and organize nyc.gov data in a easy-to-use and consistent manner.

Methods

Methods range from simple URL parameter based queries to advanced search where you can specify any combination of search criteria, logical and comparative operations across multiple data sets.

Sample code

Sample code is provided in PHP and JavaScript programming languages. Other languages can be easily used by following standard REST API call techniques.

Data sets

Over 40 property related data sets currently available from the NYC Departments of Finance, Buildings and City Planning.

Methods range from simple URL parameter based queries to advanced search where you can specify any combination of search criteria, logical and comparative operations across multiple data sets.

Simple Search

Searches for a set of records based on URL query parameters.

URI http://api.blankslate.com/api/{JSON or XML}/{dataKey}/records/search
HTTP Method GET
Path Params {dataKey} – GUID denoting the data set
Query Params {fieldName}={value} – Specify one or more field/value search criteria
{or} – Name of the field to order by.
{rp} – Records per page to return, default is 10.
{pg] – Page number for the return set, default is 1.
{em} – Exact match.
Return Codes 0 – Success 1 – Failure with failure message
Return Message <application>
<applicationKey>[Unique identifier of an application]</applicationKey>
<applicationName> [Title of the application]</applicationName>
<entity>
<entityKey> [Unique GUID for an entity]</entityKey>
<entityName/> [Name of the entity]</entityName>
<record>
<recordKey>[Unique key for record]</recordKey>
<field>
<fieldKey>Unique internal key for column</fieldKey>
<fieldName> Name of the field</fieldname>
</fieldValue> Value of the field</fieldValue>
</field>
</record>
</entity>
</application>

Advanced Search

Searches for a set of records based on a XML input query that provides additional flexibility in search criteria.

URI http://api.blankslate.com/api/{JSON or XML}/{dataKey}/records/advancedsearch
HTTP Method POST
Path Params {dataKey} – GUID denoting the data set
POST Params {queryXML} – The following XML elements make up the {queryXML}
<sort> (Optional)  – Container node for specifying the sorting order of the returned record set.
<sortFields> – Field name of the item to sort by, one or more can be added to the sort node.
<sortOrder> – The sort order of the return record set, valid values include “asc” for ascending and “desc” for decending.
<pagination> (Optional) – Specify paging for the returned record set.
<pageNumber> – The page number to return.
<recordsPerPage>  – Number of records contained in a page.
<returnFields> – Container node for fields to be included in the return record set.
<returnField> – Field name for fields to be included in the return record set.
<search> – Container node for specifying search criteria.
<fieldSet> – Container for specifying a group of fields and logical operator to search by.  fieldSet nodes can be nested within another fieldSet.  Think of fieldSet nodes as parentheses in SQL.
<operator> – Logical operator to specify the condition for fields within a fieldSet.
<field> – Container for specifying a field, comparison operator and value to search by.
<name> – Name of the field to search by.
<expression> – Comparison operator to specify the field and value for the search.
POST Example {queryXML} – Search criteria In XML format

<query>
<sort>
<sortField>{fieldname}</sortField>
<sortOrder>[desc | asc] </sortOrder>
</sort>
<pagination>
<pageNumber>[page number]</pageNumber>
<recordsPerPage>[records per page]</recordsPerPage>
</pagination>
<returnFields>
<returnField>{fieldname} </returnField>
</returnFields>
<search>
<fieldSet>
<operator>[and | or] </operator>
<fieldSet>
<operator>[and | or]</operator>
<field>
<name>{fieldName}</name>
<expression>[equals | greater-than | less-than | like] </expression>
<value> [value of field]</value>
</field>
</fieldSet>
</fieldSet>
</search>
</query>

Return Codes 0 – Success 1 – Failure with failure message
Return Message <application>
<applicationKey>[Unique identifier of an application]</applicationKey>
<applicationName> [Title of the application]</applicationName>
<entity>
<entityKey> [Unique GUID for an entity]</entityKey>
<entityName/> [Name of the entity]</entityName>
<record>
<recordKey>[Unique key for record]</recordKey>
<field>
<fieldKey>Unique internal key for column</fieldKey>
<fieldName> Name of the field</fieldname>
</fieldValue> Value of the field</fieldValue>
</field>
</record>
</entity>
</application>

Retrieve Record

Get a record specified by the dataKey and the recordKey.

URI http://api.blankslate.com/api/{JSON or XML}/{dataKey}/{recordKey}/retrieve
HTTP Method GET
Path Params {dataKey} – GUID denoting the data set
{recordKey} – Key denoting the specific record
Return Codes 0 – Success 1 – Failure with failure message
Return Message <application>
<applicationKey>[Unique identifier of an application]</applicationKey>
<applicationName> [Title of the application]</applicationName>
<entity>
<entityKey> [Unique GUID for an entity]</entityKey>
<entityName/> [Name of the entity]</entityName>
<record>
<recordKey>[Unique key for record]</recordKey>
<field>
<fieldKey>Unique internal key for column</fieldKey>
<fieldName> Name of the field</fieldname>
</fieldValue> Value of the field</fieldValue>
</field>
</record>
</entity>
</application>
Sample code is provided in PHP and JavaScript programming languages and demonstrates API calls to the Simple Search API. Other languages can be easily used by following standard REST API call techniques.

Simple Search

JavaScript Using JQuery AJAX to call Simple Search API and specify JSON as the return object.

  1. jQuery.ajax({
  2.    type: “GET”,
  3.    url: “http://api.blankslate.com/json/api/{dataKey}/records/search?Block=” + block + “&Lot=” + lot + “&or=Block&rp=30&em=true”,
  4.    dataType: ‘jsonp’,
  5.    success: function(data)
  6.    {
  7.     //Do Success
  8.    }
  9. });
PHP Using PHP CURL to call Simple Search API and specify XML as the return object.

  1. $ch = curl_init();
  2. curl_setopt($ch, CURLOPT_URL, “http://api.blankslate.com/xml/api/{dataKey}/records/search?Block=”. block. “&Lot=” .lot. “&or=Block&rp=30&em=true”);
  3. curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  4. $output = curl_exec($ch);
  5. $info = curl_getinfo($ch);
  6. curl_close($ch);
  7.  
  8. /**Output Response in XML***/
  9. $xml = simplexml_load_string ($output);
  10. return $xml;
  11. /**Output Response in XML***/
There are around 45 property related data sets currently available from the NYC Departments of Finance, Buildings and City Planning.

Partial list of data available:

NYC Department of Buildings – Properties (Source)

  • Borough
  • Bin
  • Block
  • Lot
  • House Number
  • Street Name
  • ZIP
  • Community Board
  • Obsolete_Flag
  • Landmark Flag
  • Hazmat Indicator
  • Air Indicator
  • Noise Indicator
  • Coastal Erosion Hazard Area Map Check
  • Freshwater Wetlands Map Check
  • Tidal Wetlands Map Check

NYC Department of Finance – Assessments (Source)

  • BBLE
  • Borough
  • Block
  • Lot
  • Easement
  • Owner Name
  • Building Class
  • Tax Class
  • Lot Width
  • Lot Depth
  • Extension Indicator
  • Number of Stories in Building
  • Market Value
  • Actual Land Value
  • Actual Total Value
  • Actual Exempt Land Value
  • Actual Exmpt Land Total
  • Exemption Code 1
  • Street Address
  • Zip
  • Exempt Class
  • Building Width
  • Building Depth
  • Transitional Land Value
  • Transitional Total Value
  • Transitional Exempt Land Value
  • Transitional Exempt Land Total
  • Exemption Code 2
  • Assessment Period When File Was Created
  • Assessment Year
  • VALTYPE

NYC Department of Finance – Historical Sales (Source)

  • Year
  • Borough
  • Neighborhood
  • Building Class Category
  • Tax Class at Present
  • Block
  • Lot
  • Ease-ment
  • Building Class at Present
  • Street Address
  • Zip
  • Residential Units
  • Commerical Units
  • Total Units
  • Land Square Feet
  • Gross Square Feet
  • Year Built
  • Tax Class at Time of Sale
  • Building Class at Time of Sale
  • Sale Price
  • Sale Date

NYC Department of Finance – Rolling Sales (Source)

  • Borough
  • Neighborhood
  • Building Class Category
  • Tax Class at Present
  • Block
  • Lot
  • Ease-ment
  • Building Class at Present
  • Street Address
  • Zip
  • Residential Units
  • Commerical Units
  • Total Units
  • Land Square Feet
  • Gross Square Feet
  • Year Built
  • Tax Class at Time of Sale
  • Building Class at Time of Sale
  • Sale Price
  • Sale Date

NYC Department of City Planning – Facilities (Source)

  • ID
  • BORO
  • Borough
  • CD
  • CD_DECODE
  • Block
  • Lot
  • Facility Name
  • Facility Address
  • Zip
  • FACILITY_TYPE
  • GROUP_TYPE
  • SUBGROUP_TYPE
  • CAPACITY
  • CAPACITY_TYPE
  • ACREAGE
  • PREK_8_ENROLL
  • G9_12_ENROLL
  • AGENCY_OPERATING
  • AGENCY_OVERSIGHT
  • CT2000
  • TRACT
  • COUNCIL
  • SD
  • POLICE_PREC
  • HEALTH_AREA
  • BBL
  • XCOORD
  • YCOORD