Revenue API

Global Parameters

Name Required (Y/N) Format/Value Description Example
type_of_data Y String – Must be one of the following: Contracts, Budget, Revenue, Payroll, or Spending. Allows user to select different types of data. Value must be one of the following:Contracts, Budget, Revenue, Payroll, Spending, Spending_OGE, Contracts_OGE, Spending_NYCHA, Contracts_NYCHA, Payroll_NYCHA,Budget_NYCHA, and Revenue_NYCHA Revenue
max_records N String – Max 4 Characters Allows you to set the maximum number of records retrieved to fewer than 1000 500
record_from N String – Max 15 Characters Allows you to set the starting position of the records to be retrieved 12500

Back to the top

type_of_data: Revenue

Revenue Parameters – All the parameters are optional, meaning that you can send only 1 or all of them. If you choose to not send any, you will receive random transactions in return as these parameters are the filter.

Name Required (Y/N) Type of Criteria
(Value/Range)		 Format/Value Description Applicable Filters Reference Codes Example
budget_fiscal_year N value String - YYYY Maximum 4 Characters Budget Fiscal Year. Must be exactly four characters. If no fiscal year is selected, all years are displayed Citywide Agencies and Other Government Entities(NYCHA) 2020
fiscal_year N value String - YYYY Maximum 4 Characters Fiscal Year. Must be exactly four characters. If no fiscal year is selected, all years are displayed Citywide Agencies 2019
agency_code N value String - Maximum 3 characters Identification code associated with agency. Citywide Agencies Citywide: agency codes list 127
revenue_class N value String - Maximum 3 characters(Citywide) String - Maximum 50 characters(NYCHA) Identification code assigned to the Revenue Class. For NYCHA it is searched by revenue class name. Citywide Agencies and Other Government Entities(NYCHA) Citywide: revenue class codes list NYCHA: revenue class list 790
fund_class N value String - Maximum 4 characters The identification code assigned to the fund class. This code groups the funds you defined on the Fund page for reporting purposes. Citywide Agencies Citywide: fund class codes list 001
funding_class N value String - Maximum 4 characters Identification code assigned to the Fund Class Citywide Agencies Citywide: funding class codes list IF
revenue_category N value String - Maximum 2 characters(Citywide) String - Maximum 50 characters(NYCHA) Identification code assigned to the Revenue Category. For NYCHA its searched by revenue category name. Citywide Agencies and Other Government Entities(NYCHA) Citywide: Revenue Category Codes List
NYCHA: Revenue Category List 		71
revenue_source N value String - Maximum 5 characters Identification code assigned to the Revenue Source Citywide Agencies Citywide: Revenue Source Codes List 1008
revenue_expense_category N value String - Maximum 20 characters Identification code association to expenditure type accounts. Citywide Agencies and Other Government Entities(NYCHA) NYCHA: Revenue Expense Category Codes List 662
adopted N Range String - Maximum 18 Characters A dollar amount for the total amount of a budget that was officially approved by the legislative body for a specified time period. Citywide Agencies and Other Government Entities(NYCHA) 250000.00
modified N Range String - Maximum 18 Characters A dollar amount for the current, to-date, budget amount. Citywide Agencies and Other Government Entities(NYCHA) 250000.00
recognized N Range String - Maximum 18 Characters The dollar amount posted to the journals as a result of a transaction. Citywide Agencies and Other Government Entities(NYCHA) 250000.00
conditional_category N value String - Maximum 2 Characters The identification id assigned to the conditional category. Citywide Agencies Citywide: Conditional Category Ids 1
remaining N Range String - Maximum 18 Characters A dollar amount for funds remaining. Citywide Agencies and Other Government Entities(NYCHA) 250000.00
budget_type N value String - Maximum 50 characters Is the account type. Other Government Entities(NYCHA) NYCHA: Budget Types List Other Revenues
budget_name N value String - Maximum 100 characters Is the account name under each account type.The lowest level within the Authority’s chart of accounts that identifies the expenditure type. Examples of Accounts are: supplies, equipment, contracts, travel, and utilities. Other Government Entities(NYCHA) NYCHA: Budget Names List Other
funding_source N value String - Maximum 4 characters Is the account type. Other Government Entities(NYCHA) NYCHA: Funding source codes List M016
responsibility_center N value String - Maximum 10 characters A Development or Department where expenses will be budgeted and recorded. Other Government Entities(NYCHA) NYCHA: Responsibility Center Codes List PM21870
program N value String - Maximum 6 characters Unique identifier used primarily to specify Grant Year for Funding Source. Program to Eliminate the Gap (PEG) - Is a financial package of ideas to close a given financial deficit. Other Government Entities(NYCHA) NYCHA: Program Codes List S18AHP
project N value String - Maximum 6 characters A budget line item identifier used for external reporting and billing purposes.. Other Government Entities(NYCHA) NYCHA: Project Codes List CCF023

Back to the top

Possible response columns:

The user would be able to select which columns he would like to view in his output. Below mentioned are the possible column names for budget domain. The user should include the required column names in the request xml in an element called <response_columns>

(Citywide)Response Column Names
Response Column Names
agency budget_fiscal_year
fiscal_year funding_class
revenue_category revenue_class
revenue_source fund_class
adopted modified
recognized closing_classification_name
 
(Other Government Entities - NYCHA) Response Column Names
budget_fiscal_year project
adopted program
modified budget_type
recognized budget_name
remaining revenue_category
revenue_expense_category revenue_class
funding_source closing_classification_name
responsibility_center

Back to the top

Predefined Entities in XML

The user has to encode the names using the predefined entities list embedded below, while searching using names (payee_name, budget_name, vendor, and purpose). The table below lists the five XML predefined entities. The "Name" column mentions the entity's name. The "Character" column shows the character. To render the character, the format &name; is used; for example, &amp; renders as &.

Name Character Description Representation Example Text Example Request/Response
quot " double quotation mark &quot; “Gilbane” &quot;Gilbane&quot;
amp & ampersand &amp; Mckissack & Mckissack Mckissack &amp; Mckissack
apos ' apostrophe (apostrophe-quote) &apos; ‘turner’ &apos; turner &apos;
lt < less-than sign &lt; <gilbane building &lt;gilbane building
gt > greater-than sign &gt; gilbane building> gilbane building&gt;

Back to the top

Sample XML Requests and Responses

The following xml file will specify API method calls and the details for each call.

The request xml would include global parameters which specify the selected domain, records from and maximum records to return in response. It also includes search parameters along with requested response column.

In the response xml, the actual search parameters that were sent will be returned in an element called <search_criteria> along with the actual result for a given search criteria will be displayed in an element called <result_records>.

The total number of resulting records for a given search criteria will be displayed within an element called <record_count>, which helps user to view the total number of records found for a given search criteria.

The response xml also includes status messages for the result. If there is an error, corresponding error code along with description will be included in an element called <messages> for user reference.

Back to the top

Sample Request: Revenue Transactions

<request>
  <type_of_data>Revenue</type_of_data>
  <records_from>1</records_from>
  <max_records>5</max_records>
  <search_criteria>
    <criteria>
      <name>budget_fiscal_year</name>
      <type>value</type>
      <value>2013</value>
    </criteria>
    <criteria>
      <name>fiscal_year</name>
      <type>value</type>
      <value>2013</value>
    </criteria>
    <criteria>
      <name>agency_code</name>
      <type>value</type>
      <value>040</value>
    </criteria>
    <criteria>
      <name>revenue_category</name>
      <type>value</type>
      <value>22</value>
    </criteria>
    <criteria>
      <name>revenue_source</name>
      <type>value</type>
      <value>00460</value>
    </criteria>
    <criteria>
      <name>revenue_class</name>
      <type>value</type>
      <value>010</value>
    </criteria>
    <criteria>
      <name>funding_class</name>
      <type>value</type>
      <value>C</value>
    </criteria>
    <criteria>
      <name>fund_class</name>
      <type>value</type>
      <value>001</value>
    </criteria>
    <criteria>
      <name>adopted</name>
      <type>range</type>
      <start>10000.00</start>
      <end>250000000.00</end>
    </criteria>
    <criteria>
      <name>modified</name>
      <type>range</type>
      <start>10000.00</start>
      <end>250000000.00</end>
    </criteria>
    <criteria>
      <name>recognized</name>
      <type>range</type>
      <start>10000.00</start>
      <end>2500000000.00</end>
    </criteria>
  </search_criteria>
  <response_columns>
    <column>agency</column>
    <column>budget_fiscal_year</column>
    <column>fiscal_year</column>
    <column>fund_class</column>
    <column>funding_class</column>
    <column>revenue_category</column>
    <column>revenue_source</column>
    <column>revenue_class</column>
    <column>adopted</column>
    <column>modified</column>
    <column>recognized</column>
    <column>closing_classification_name</column>
  </response_columns>
</request>

Back to the top

Sample Response: Revenue Transactions

<response>
  <status>
    <result>success</result>
  </status>
  <request_criteria>
    <request>
      <type_of_data>Revenue</type_of_data>
      <records_from>1</records_from>
      <max_records>5</max_records>
      <search_criteria>
        <criteria>
          <name>budget_fiscal_year</name>
          <type>value</type>
          <value>2013</value>
        </criteria>
        <criteria>
          <name>fiscal_year</name>
          <type>value</type>
          <value>2013</value>
        </criteria>
        <criteria>
          <name>agency_code</name>
          <type>value</type>
          <value>040</value>
        </criteria>
        <criteria>
          <name>revenue_category</name>
          <type>value</type>
          <value>22</value>
        </criteria>
        <criteria>
          <name>revenue_source</name>
          <type>value</type>
          <value>00460</value>
        </criteria>
        <criteria>
          <name>revenue_class</name>
          <type>value</type>
          <value>010</value>
        </criteria>
        <criteria>
          <name>funding_class</name>
          <type>value</type>
          <value>C</value>
        </criteria>
        <criteria>
          <name>fund_class</name>
          <type>value</type>
          <value>001</value>
        </criteria>
        <criteria>
          <name>adopted</name>
          <type>range</type>
          <start>10000.00</start>
          <end>250000000.00</end>
        </criteria>
        <criteria>
          <name>modified</name>
          <type>range</type>
          <start>10000.00</start>
          <end>250000000.00</end>
        </criteria>
        <criteria>
          <name>recognized</name>
          <type>range</type>
          <start>10000.00</start>
          <end>2500000000.00</end>
        </criteria>
      </search_criteria>
      <response_columns>
        <column>agency</column>
        <column>budget_fiscal_year</column>
        <column>fiscal_year</column>
        <column>fund_class</column>
        <column>funding_class</column>
        <column>revenue_category</column>
        <column>revenue_source</column>
        <column>revenue_class</column>
        <column>adopted</column>
        <column>modified</column>
        <column>recognized</column>
        <column>closing_classification_name</column>
      </response_columns>
    </request>
  </request_criteria>
  <result_records>
    <record_count>80</record_count>
    <revenue_transactions>
      <transaction>
        <agency>Department of Education</agency>
        <revenue_category>CHARGES FOR SERVICES</revenue_category>
        <revenue_source>EDUCATION SERVICES/FEES</revenue_source>
        <fund_class>General Fund</fund_class>
        <funding_class>CITY FUNDS</funding_class>
        <revenue_class>GENERAL GOVERNMENTAL CHARGES</revenue_class>
        <budget_fiscal_year>2013</budget_fiscal_year>
        <fiscal_year>2013</fiscal_year>
        <adopted>20073968</adopted>
        <modified>20073968</modified>
        <recognized>239377.44</recognized>
        <closing_classification_name>Collected Revenue</closing_classification_name>
      </transaction>
    </revenue_transactions>
  </result_records>
</response>

Back to the top

Sample Request: Revenue Transactions(OTHER GOVERNMENT ENTITIES - NYCHA)

<request>
  <type_of_data>Revenue_NYCHA</type_of_data>
  <records_from>1</records_from>
  <max_records>5</max_records>
  <search_criteria>
    <criteria>
      <name>budget_fiscal_year</name>
      <type>value</type>
      <value>2018</value>
    </criteria>
      <criteria>
      <name>revenue_category</name>
      <type>value</type>
      <value>operating reserve</value>
    </criteria>
    <criteria>
      <name>funding_source</name>
      <type>value</type>
      <value>L083</value>
    </criteria>
    <criteria>
      <name>revenue_class</name>
      <type>value</type>
      <value>mixed finance</value>
    </criteria>
    <criteria>
      <name>revenue_expense_category</name>
      <type>value</type>
      <value>57876</value>
    </criteria>
    <criteria>
      <name>responsibility_center</name>
      <type>value</type>
      <value>K008300</value>
    </criteria>
    <criteria>
      <name>budget_name</name>
      <type>value</type>
      <value>DWELLING RENT</value>
    </criteria>
    <criteria>
      <name>budget_type</name>
      <type>value</type>
      <value>REVENUE FROM OPERATIONS</value>
    </criteria>
    <criteria>
      <name>program</name>
      <type>value</type>
      <value>000000</value>
    </criteria>
    <criteria>
      <name>project</name>
      <type>value</type>
      <value>000000</value>
    </criteria>
    <criteria>
      <name>adopted</name>
      <type>range</type>
      <start>-10000000.00</start>
      <end>250000000.00</end>
    </criteria>
    <criteria>
      <name>modified</name>
      <type>range</type>
      <start>-10000000.00</start>
      <end>250000000.00</end>
    </criteria>
    <criteria>
      <name>recognized</name>
      <type>range</type>
      <start>-10000000.00</start>
      <end>2500000000.00</end>
    </criteria>
    <criteria>
      <name>remaining</name>
      <type>range</type>
      <start>-10000000.00</start>
      <end>2500000000.00</end>
    </criteria>
  </search_criteria>
  <response_columns>
    <column>adopted</column>
    <column>budget_fiscal_year</column>
    <column>budget_name</column>
    <column>budget_type</column>
    <column>closing_classification_name</column>
    <column>revenue_expense_category</column>
    <column>funding_source</column>
    <column>modified</column>
    <column>program</column>
    <column>project</column>
    <column>recognized</column>
    <column>remaining</column>
    <column>responsibility_center</column>
    <column>revenue_category</column>
    <column>revenue_class</column>
  </response_columns>
</request>

Back to the top

Sample Response: Revenue Transactions(OTHER GOVERNMENT ENTITIES - NYCHA)

<response>
  <status>
    <result>success</result>
  </status>
  <request_criteria>
    <request>
      <type_of_data>Revenue_NYCHA</type_of_data>
      <records_from>1</records_from>
      <max_records>5</max_records>
      <search_criteria>
        <criteria>
          <name>budget_fiscal_year</name>
          <type>value</type>
          <value>2018</value>
        </criteria>
          <criteria>
          <name>revenue_category</name>
          <type>value</type>
          <value>operating reserve</value>
        </criteria>
        <criteria>
          <name>funding_source</name>
          <type>value</type>
          <value>L083</value>
        </criteria>
        <criteria>
          <name>revenue_class</name>
          <type>value</type>
          <value>mixed finance</value>
        </criteria>
        <criteria>
          <name>revenue_expense_category</name>
          <type>value</type>
          <value>57876</value>
        </criteria>
        <criteria>
          <name>responsibility_center</name>
          <type>value</type>
          <value>K008300</value>
        </criteria>
        <criteria>
          <name>adopted</name>
          <type>range</type>
          <start>-10000000.00</start>
          <end>250000000.00</end>
        </criteria>
        <criteria>
          <name>modified</name>
          <type>range</type>
          <start>-10000000.00</start>
          <end>250000000.00</end>
        </criteria>
        <criteria>
          <name>recognized</name>
          <type>range</type>
          <start>-10000000.00</start>
          <end>2500000000.00</end>
        </criteria>
        <criteria>
          <name>remaining</name>
          <type>range</type>
          <start>-10000000.00</start>
          <end>2500000000.00</end>
        </criteria>
      </search_criteria>
      <response_columns>
        <column>adopted</column>
        <column>budget_fiscal_year</column>
        <column>budget_name</column>
        <column>budget_type</column>
        <column>closing_classification_name</column>
        <column>revenue_expense_category</column>
        <column>funding_source</column>
        <column>modified</column>
        <column>program</column>
        <column>project</column>
        <column>recognized</column>
        <column>remaining</column>
        <column>responsibility_center</column>
        <column>revenue_category</column>
        <column>revenue_class</column>
      </response_columns>
    </request>
  </request_criteria>
  <result_records>
    <record_count>1</record_count>
    <revenue_transactions>
      <transaction>
        <adopted>-192158.00</adopted>
        <budget_fiscal_year>2018</budget_fiscal_year>
        <budget_name>DWELLING RENT</budget_name>
        <budget_type>REVENUE FROM OPERATIONS</budget_type>
        <closing_classification_name>COLLECTED REVENUE</closing_classification_name>
        <revenue_expense_category>RENT COLLECTION LOSS</revenue_expense_category>
        <funding_source>LIHTC - MARLBORO</funding_class>
        <modified>-192158.00</modified>
        <program>No Program Assigned</program>
        <project>No Project Assigned</project>
        <recognized>-80025.23</recognized>
        <remaining>-112132.77</remaining>
        <responsibility_center>MARLBORO</responsibility_center>
        <revenue_category>OPERATING RESERVE</revenue_category>
        <revenue_class>Mixed Finance</revenue_class>                  
      </transaction>
    </revenue_transactions>
  </result_records>
</response>

Back to the top

Status Codes and Messages

Status messages are categorized and displayed as status codes with short description for the user to understand the cause of the error. In case of an error no result records will be displayed and the error message will be displayed inside the <message> XML element as shown below. See here for list of status codes and messages.

Example: Result is Success 

<status>
  <result>success</result>
  <messages>
    <message> <code>1</code>
      <description> The status is still a success but there are no results found for given search criteria</description>
    </message>
  </messages>
</status>
Example: Result is Failure 

<status>
  <result>error</result>
  <messages>
    <message> <code>1000</code >
      <description>Required parameter 'type_of_data' is missing</description>
    </message>
  </messages>
</status>

Back to the top

Status Code Description
1 The request is a success but there are no results found for given search criteria.
1000 Required parameter 'type_of_data' is missing.
1001 Invalid value 'BudgetRequest' is provided for 'type_of_data'. Valid values are Budget, Contracts, Spending, Payroll.
1002 Provided value '2.1' for 'records_from' is not an integer. Valid value is a number value without decimal places
1003 Total number of requested records '1001' exceeds allowed limit of '1000' records
1101 Provided request parameter 'date' is not valid for 'Budget' domain. Valid values are 'year, agency_code, department_code, budget_code, revenue_expense_category, adopted, modified, pre_encumbered, encumbered, cash_expense, post_adjustment, accrued_expense
1102 No value is provided for request parameter 'year'.
1103 Provided value '20000' for request parameter 'year' is not valid year.
1104 Provided 'start' value '200s' for request parameter 'adopted' is not valid amount.
1105 Provided start value '1000' is greater than end value '500' for request parameter 'adopted'.
1106 Provided response column 'agencyname' value is not allowed for 'Budget' domain. Valid values are 'agency, department, revenue_expense_category, budget_code, budget_name, modified, adopted, pre_encumbered, encumbered, cash_expense, post_adjustment, accrued_expense'.
1107 Provided value for criteria (1) type element 'valeu' is invalid. Valid values are 'value, range'
1108 Provided value 'abcd' for request parameter 'agency_code' exceeds maximum allowed '3' characters.
1109 Provided 'start' value '12345678901234567890' for request parameter 'adopted' exceeds maximum allowed '18' characters.
1110 Request parameter 'agency_code' does not support range values.
 

Overview

In July of 2010 the New York City Comptroller’s Office launched Checkbook NYC, an online transparency tool that for the first time placed the City’s day-to-day spending in the public domain. Using an intuitive dashboard approach that combines a series of graphs and user-friendly tables, Checkbook NYC provides up-to-date information about the City's financial condition.

Checkbook NYC has been ranked the top transparency tool in the nation for tracking government spending by the United States Public Interest Research Group, and was named New York City 2013 “Best External Application” by Government Technology Magazine.


 

Spotlight