Open Data - User Guide

# Developer Resources

This section is primarily intended for developers looking to use the APIs and other options available to access data.

# API

The Open Data Portal provides developers with a standard HTTP GET API resource that returns data in JSON output. Our API supports OData query language syntax that can help you navigate and work easily with the API.

We currently support the following OData language operations:

  • $top
  • $skip
  • $filter
  • $select
  • $orderby
  • like(contains)
  • Not Equal
  • Greater Than
  • Less Than

This section describes ways you can interact with the API using OData syntax.

WARNING

No Token is required to access API however we monitor and throttle any excess use and misuse of our API.

# Working with API

API member naming accepts certain casing patterns. General convention is camelCasing or ProperCase. It also accepts underscores in place of UpperCase. For example, these are all valid API Url's]


https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations

https://datahub-v2.arlingtonva.us/api/recreation/parkFacilityReservations

https://datahub-v2.arlingtonva.us/api/recreation/park_facility_reservations

But this isn't valid:


https://datahub-v2.arlingtonva.us/api/recreation/parkfacilityreservations

TIP

We recommend following the same casing as displayed on the Portal to keep things simple and consistent

A standard API call may look like:

return new Promise(resolve => {
  fetch(
    `https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations`
    ).then(response => {
      resolve(response.json());
    });
});

ALERT

By default, API returns 10 rows only. To get additional data, continue reading...

# Paginating Data

By default, API returns 10 records total. You can increase the return size by passing in $top to the querystring.

For example:


https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations?$top=50

ALERT

The maximum size limit API can return is 100,000 records at once.

You can paginate and work your way through the full dataset using $skip and $top operations. For example,


https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations?$skip=50&$top=100

TIP

It is recommended to break the data in smaller chunks using $top and $skip for optimal performance as opposed to pulling full dataset

# Filtering Data

Use $filter OData syntax to filter data out. In the example below, Park reservations are filtered to only return Tennis Court reservations.


//Return Tennis Court reservations only
https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations?$filter=ReservationFacilityTypeCode eq 'TENIS'

You can combine multiple $filter operations by separating with either OR, or AND.


//Return Tennis Court reservations in Barcroft Park Location
https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations?$filter=ReservationFacilityTypeCode eq 'TENIS' and LocationName eq 'Barcroft Park'

# Ordering Data

To return output in Ascending or Descending order, use $orderby desc or asc


//Return park field reservations by reservationBeginDate in descending order
https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations?$orderby=reservationBeginDate desc

# Limiting Selection

You can limit the number of selected columns by using $select. You can specify multiple columns separated by comma.


https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations?$select=reservationBeginDate,locationName,reservationTypeName

# Not Equal To


https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations?$filter=ReservationFacilityTypeCode ne 'TENIS'

# Like (Contains)


https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations?$filter=contains(ReservationFacilityTypeCode,'TENIS')

# Greater Than


https://datahub-v2.arlingtonva.us/api/Recreation/ParkFacilityReservations?$filter=reservationBeginDate gt 2020-08-15

TIP

For any date data types, use standard Javascript ISO 8601 format (YYYY-MM-DD{T}HH-MM-SS{Z}). For example, 2020-08-15T14:00:00Z

# Less Than


https://datahub-v2.arlingtonva.us/api/Recreation/ParkFacilityReservations?$filter=reservationBeginDate lt 2020-08-15

# Performance Tips

  • For best performance, always limit the resultset by using one or more combination of OData operations as shown above.

  • You can combine multiple OData operations to narrow down the ouptut, for example


https://datahub-v2.arlingtonva.us/api/recreation/ParkFacilityReservations?$select=reservationBeginDate,locationName,reservationTypeName&$skip=100&$top=10&$filter=ReservationFacilityTypeCode eq 'TENIS' and LocationName eq 'Barcroft Park'&$orderby=reservationBeginDate desc

  • Avoid using blanket queries and instead use $select to limit column selections

  • Repeated queries and query patterns are cached so its recommended to reuse as much as possible

# Downloadable Data

All data available in the portal is available for download.

# File Formats

Data is available for download in one of the following formats: csv, txt, zip, gz, xls. You will see the file extension and file size listed in the button for “Download Dataset.”

  • .txt - Files are pipe (|) delimited. Download file and import it in a program such as Microsoft Excel using the pipe character (|) as the delimiter

  • .gz - – Zipped files available to optimize storage space and download size. To decompress this file, you will need a program such as Winzip or 7-zip. The file can then be imported in the program of choice

  • .csv - comma seperated files. Easily imported to excel

  • .xls - standard Excel file

  • .json - are standard json formatted files you can use to program against

Last Updated: 9/30/2020, 4:44:35 PM

←