Budget API

 

Global Parameters

Name Required (Y/N) Format/Value Description Example
type_of_data Y String – Must be one of the following:     
Contracts, Budget, 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 Budget
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: Budget

Budget 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
year N Value String - YYYY Maximum 4 Characters Fiscal Year. Must be exactly 4 characters. If no fiscal year is selected, all years are displayed Citywide Agencies and   2005
budget_code N Value String - Maximum 4 characters Budget code identifier. Must be exactly 4 characters. Citywide Agencies Citywide: Budget codes list 0702
budget_code_name N Value String - Maximum 100 characters Budget name Identifier. Full name can be used or first characters of it. Minimum 1 character. Citywide Agencies Citywide: Budget names list COLUMBI
agency_code N Value String - Maximum 3 characters Identification code associated with agency. Citywide Citywide: agency codes list 127
department_code N Value String – Maximum 3 characters An identification code associated with a department on the accounting line. Citywide Citywide department codes list 561
expense_category N Value String - Maximum 20 characters An identification code associated with Expense Category. Citywide Agencies Citywide: expense category codes list NYCHA: 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
pre_encumbered N Range String – Maximum 18 Characters A dollar amount (including both negative and positive) for the amount of money that has entered the pre-encumbered state for a budget or allotment line. Citywide Agencies   250000.00
encumbered N Range String – Maximum 18 Characters A dollar amount (including both negative and positive) for the total dollar amount of funds that have entered an encumbered state. Citywide Agencies and Other Government Entities (NYCHA)   250000.00
accrued_expense N Range String – Maximum 18 Characters A dollar amount (including both negative and positive) for the amount of expenditures against a budget that have not been paid. Citywide Agencies   250000.00
cash_expense N Range String – Maximum 18 Characters A dollar amount (including both negative and positive) for the amount of expenditures against a budget that have been paid, thereby reducing cash. Citywide Agencies   250000.00
post_ adjustment N Range String – Maximum 18 Characters A dollar amount (including both negative and positive) for the amount represents the changes to Accrued Expenditures in fiscal years after the budget year. Citywide Agencies   250000.00
conditional_category N value String- Maximum 2 characters Identification id associated with conditional category. Citywide Agencies Citywide: Conditional Category Ids 1
budget_type N Value String - Maximum 50 characters Is the account type. Other Government Entities (NYCHA) NYCHA: Budget type list 0702
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 COLUMBI
funding_source N Value String - Maximum 4 characters Is the account type. Other Government Entities (NYCHA) NYCHA: Funding Source List 0702
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 Code List 2500
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 Code List 2500
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 Code List 2500
committed N Range String – Maximum 18 Characters A dollar amount (including both negative and positive) for the total dollar amount of funds that have entered have been committed. Sum of encumbered and actual amount should give total committed amount. Other Government Entities (NYCHA)   250000.00
actual_amount N Range String – Maximum 18 Characters A dollar amount (including both negative and positive) for the total dollar amount of funds that have entered have been spent. Other Government Entities (NYCHA)   250000.00

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
agency year
department post_adjustment
expense_category modified
budget_code adopted
budget_name encumbered
pre_encumbered cash_expense
accrued_expense committed
 
(Other Government Entities - NYCHA) Response Column Names
actual_amount project
adopted remaining
budget_name responsibility_center
budget_type year
committed funding_source
encumbered modified
expense_category program

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: Budget Transactions (Citywide) 

<request>
  <type_of_data>Budget</type_of_data>
  <records_from>1</records_from>
  <max_records>1</max_records>
  <search_criteria>
    <criteria>
      <name>year</name>
      <type>value</type>
      <value>2018</value>
    </criteria>
    <criteria>
      <name>budget_code</name>
      <type>value</type>
      <value>5802</value>
    </criteria>
    <criteria>
      <name>agency_code</name>
      <type>value</type>
      <value>846</value>
    </criteria>
    <criteria>
      <name>department_code</name>
      <type>value</type>
      <value>006</value>
    </criteria>
    <criteria>
      <name>expense_category</name>
      <type>value</type>
      <value>100</value>
    </criteria>
    <criteria>
      <name>adopted</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000.00</end>
    </criteria>
    <criteria>
      <name>modified</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000.00</end>
    </criteria>
    <criteria>
      <name>pre_encumbered</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000.00</end>
    </criteria>
    <criteria>
      <name>encumbered</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000.00</end>
    </criteria>
    <criteria>
      <name>cash_expense</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000.00</end>
    </criteria>
    <criteria>
      <name>post_adjustment</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000.00</end>
    </criteria>
    <criteria>
      <name>accrued_expense</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000.00</end>
    </criteria>
  </search_criteria>
  <response_columns>
    <column>agency</column>
    <column>year</column>
    <column>department</column>
    <column>expense_category</column>
    <column>budget_code</column>
    <column>budget_name</column>
    <column>modified</column>
    <column>committed</column>
    <column>adopted</column>
    <column>pre_encumbered</column>
    <column>encumbered</column>
    <column>cash_expense</column>
    <column>post_adjustment</column>
    <column>accrued_expense</column>
  </response_columns>
</request>

Back to the top     

Sample Response: Budget Transactions(Citywide) 

<response>
  <status>
    <result>success</result>
  </status>
  <request_criteria>
    <request>
      <type_of_data>Budget</type_of_data>
      <records_from>1</records_from>
      <max_records>1</max_records>
      <search_criteria>
        <criteria>
          <name>year</name>
          <type>value</type>
          <value>2018</value>
        </criteria>
        <criteria>
          <name>budget_code</name>
          <type>value</type>
          <value>5802</value>
        </criteria>
        <criteria>
          <name>agency_code</name>
          <type>value</type>
          <value>846</value>
        </criteria>
        <criteria>
          <name>department_code</name>
          <type>value</type>
          <value>006</value>
        </criteria>
        <criteria>
          <name>expense_category</name>
          <type>value</type>
          <value>100</value>
        </criteria>
        <criteria>
          <name>adopted</name>
          <type>range</type>
          <start>0.00</start>
          <end>10000.00</end>
        </criteria>
        <criteria>
          <name>modified</name>
          <type>range</type>
          <start>0.00</start>
          <end>10000.00</end>
        </criteria>
        <criteria>
          <name>pre_encumbered</name>
          <type>range</type>
          <start>0.00</start>
          <end>10000.00</end>
        </criteria>
        <criteria>
          <name>encumbered</name>
          <type>range</type>
          <start>0.00</start>
          <end>10000.00</end>
        </criteria>
        <criteria>
          <name>cash_expense</name>
          <type>range</type>
          <start>0.00</start>
          <end>10000.00</end>
        </criteria>
        <criteria>
          <name>post_adjustment</name>
          <type>range</type>
          <start>0.00</start>
          <end>10000.00</end>
        </criteria>
        <criteria>
          <name>accrued_expense</name>
          <type>range</type>
          <start>0.00</start>
          <end>10000.00</end>
        </criteria>
      </search_criteria>
      <response_columns>
        <column>agency</column>
        <column>year</column>
        <column>department</column>
        <column>expense_category</column>
        <column>budget_code</column>
        <column>budget_name</column>
        <column>modified</column>
        <column>committed</column>
        <column>adopted</column>
        <column>pre_encumbered</column>
        <column>encumbered</column>
        <column>cash_expense</column>
        <column>post_adjustment</column>
        <column>accrued_expense</column>
      </response_columns>
    </request>
  </request_criteria>
  <result_records>
    <record_count>1</record_count>
    <budget_transactions>
      <transaction>
        <agency>Department of Parks and Recreation</agency>
        <year>2018</year>
        <department>MAINT & OPERATIONS - OTPS</department>
        <expense_category>SUPPLIES + MATERIALS - GENERAL</expense_category>
        <budget_code>5802</budget_code>
        <budget_name>Columbia University W Harlem Piers Park</budget_name>
        <budget_amounts>
          <modified>0</modified>
          <committed></committed>0
          <adopted>0</adopted>
        </budget_amounts>
        <expenditure_amounts>
          <pre_encumbered>0</pre_encumbered>
          <encumbered>0</encumbered>
          <cash_expense>0</cash_expense>
          <post_adjustment>0</post_adjustment>
          <accrued_expense>0</accrued_expense>
        </expenditure_amounts>
      </transaction>
    </budget_transactions>
  </result_records>
</response>

Back to the top     

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

<request>
  <type_of_data>Budget_NYCHA</type_of_data>
  <records_from>1</records_from>
  <max_records>1</max_records>
  <search_criteria>
    <criteria>
      <name>year</name>
      <type>value</type>
      <value>2018</value>
    </criteria>
    <criteria>
      <name>expense_category</name>
      <type>value</type>
      <value>58059</value>
    </criteria>        
    <criteria>
      <name>funding_source</name>
      <type>value</type>
      <value>F006</value>
    </criteria>   
    <criteria>
      <name>responsibility_center</name>
      <type>value</type>
      <value>9900500</value>
    </criteria>
    <criteria>
      <name>project</name>
      <type>value</type>
      <value>V00160</value>
    </criteria>
    <criteria>
      <name>program</name>
      <type>value</type>
      <value>FPABNX</value>
    </criteria>
    <criteria>
      <name>adopted</name>
      <type>range</type>
      <start>0</start>
      <end>10000000</end>
    </criteria>
    <criteria>
      <name>modified</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000000</end>
    </criteria>
    <criteria>
      <name>encumbered</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000000</end>
    </criteria>
    <criteria>
      <name>committed</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000000</end>
    </criteria>
    <criteria>
      <name>actual_amount</name>
      <type>range</type>
      <start>0.00</start>
      <end>10000000</end>
    </criteria>        
    <criteria>
      <name>budget_type</name>
      <type>value</type>
      <value>O.T.P.S.</value>
    </criteria>
    <criteria>
      <name>budget_name</name>
      <type>value</type>
      <value>LEASES</value>
    </criteria>
  </search_criteria>
  <response_columns>        
    <column>actual_amount</column>
    <column>adopted</column>
    <column>modified</column>
    <column>remaining</column>
    <column>budget_name</column>
    <column>budget_type</column>
    <column>committed</column>
    <column>encumbered</column>
    <column>expense_category</column>
    <column>project</column>
    <column>responsibility_center</column>
    <column>funding_source</column>       
    <column>program</column>
    <column>year</column>
  </response_columns>
</request>

Back to the top     

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

<response>
  <status>
    <result>success</result>
  </status>
  <request_criteria>
   <request>
     <type_of_data>Budget_NYCHA</type_of_data>
     <records_from>1</records_from>
     <max_records>1</max_records>
     <search_criteria>
       <criteria>
         <name>year</name>
         <type>value</type>
         <value>2018</value>
       </criteria>
       <criteria>
         <name>expense_category</name>
         <type>value</type>
         <value>58059</value>
       </criteria>        
       <criteria>
         <name>funding_source</name>
         <type>value</type>
         <value>F006</value>
       </criteria>   
       <criteria>
         <name>responsibility_center</name>
         <type>value</type>
         <value>9900500</value>
       </criteria>
       <criteria>
         <name>project</name>
         <type>value</type>
         <value>V00160</value>
       </criteria>
       <criteria>
         <name>program</name>
         <type>value</type>
         <value>FPABNX</value>
       </criteria>
       <criteria>
         <name>adopted</name>
         <type>range</type>
         <start>0</start>
         <end>10000000</end>
       </criteria>
       <criteria>
         <name>modified</name>
         <type>range</type>
         <start>0.00</start>
         <end>10000000</end>
       </criteria>
       <criteria>
         <name>encumbered</name>
         <type>range</type>
         <start>0.00</start>
         <end>10000000</end>
       </criteria>
       <criteria>
         <name>committed</name>
         <type>range</type>
         <start>0.00</start>
         <end>10000000</end>
       </criteria>
       <criteria>
         <name>actual_amount</name>
         <type>range</type>
         <start>0.00</start>
         <end>10000000</end>
       </criteria>        
       <criteria>
         <name>budget_type</name>
         <type>value</type>
         <value>O.T.P.S.</value>
       </criteria>
       <criteria>
         <name>budget_name</name>
         <type>value</type>
         <value>LEASES</value>
       </criteria>
     </search_criteria>
     <response_columns>        
       <column>actual_amount</column>
       <column>adopted</column>
       <column>modified</column>
       <column>remaining</column>
       <column>budget_name</column>
       <column>budget_type</column>
       <column>committed </column>
       <column>encumbered </column>
       <column>expense_category</column>
       <column>project</column>
       <column>responsibility_center</column>
       <column>funding_source</column>       
       <column>program</column>
       <column>year</column>
     </response_columns>
   </request>
 </request_criteria>
 <result_records>
   <record_count>1</record_count>
   <budget_transactions>
     <transaction>
      <budget_type>O.T.P.S.</budget_type>
      <budget_name>LEASES</budget_name>
      <expense_category>RENTAL LEASE / LAND & BUILDINGS</expense_category>
      <funding_source>SECTION 8/VOUCHER PROGRAM</funding_source>
      <responsibility_center>CENTRALLY MANAGED ACCOUNTS - FACILITIES</responsibility_center>
      <program>FACILITY PLANNING ADM - BRONX</program>
      <project>CONTRACT NY005-V00-160</project>
      <budget_amounts>
        <modified>0.00</modified>
        <adopted>0.00</adopted>
        <remaining>-7674.07</remaining>
      </budget_amounts>
      <expenditure_amounts>
        <committed>7674.07</committed>
        <encumbered>0.00</encumbered>
        <actual_amount>7674.07</actual_amount>
      </expenditure_amounts>
    </transaction>
  </budget_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 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 request is a success but there are no results found for given search criteria</description>
    </message>
  </messages>
</status>

  • Result is Failure:

    <status>
  <result>failure</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, 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, 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