APIer

Grey Matter's real-time Spreadsheet-to-JSON transformation microservice.

Endpoints

Endpoint	Method	Description	Parameters
/alive	GET	Simple health check route.	None
/configs	GET	Returns APIer's current configuration.	None
/sheets	GET	Returns a list of all sheets.	None
/sheets/{sheet_name or sheet_id}	GET	Returns a paginated JSON array of entries (rows) from the sheet referred to by the path parameter, if one exists.	All Query Parameters
/sheets/all	GET	Returns a list of all entries, grouped and paginated by sheet. Note, the query parameters are applied to every sheet.	max_rows, start

The documentation route is disabled by default, but can be configured by setting the DOCS_URL.

Query Parameters

When crafting queries, follow these guidelines:

1. Column names without spaces should not be quoted.

2. String values should be quoted.

3. Column names with spaces must be quoted.

4. Column names and values are case-sensitive.

5. Python's and, or , and not operators replace traditional &&, || , and !.

q

The query string to apply. The query string must be formatted according to the python eval syntax. Values should be quoted, unless non-strings. Likewise, the full range of boolean and numerical operators are available.

Example: http://localhost:8000/sheets/base?q=(state=="Washington") and (date=="2020-01-31")

date must be represented in ISO 8601 format.

In production it's best practice to URL encode this query string. The example is unencoded for documentation purposes.

cols

Allows for partial column selection. Every column becomes a field in the returned JSON. This filter can be useful to scale the expressiveness and response size of the returned objects. Accepts both comma delimited values or individual query parameters.

Example: http://localhost:8000/sheets/base?cols=date,state,fips,cases http://localhost:8000/sheets/base?cols=date&cols=state&cols=fips&cols=cases

sortby

Sorts data by provided column names. Accepts both comma delimited values or individual query parameters.

Example: http://localhost:8000/sheets/base?sortby=date,state http://localhost:8000/sheets/base?sortby=date&sortby=state

ascending

Comma delimited list of integers denoting which sorting field to sort in ascending order. A non-zero value enables ascending order for the sorting filter found in the sortby parameter at the same index. This parameter's array length cannot exceed the length of the sortby array, but can be less then. Missing values will be defaulted to ascending order.

Examples:

All ascending:

• http://localhost:8000/sheets/base?sortby=date,state

• http://localhost:8000/sheets/base?sortby=date,state&ascending=1

• http://localhost:8000/sheets/base?sortby=date,state&ascending=1,1

All descending: http://localhost:8000/sheets/base?sortby=date,state&ascending=0,0

Mixed: http://localhost:8000/sheets/base?sortby=date,state&ascending=0

max_rows

A positive non-zero integer which sets the limit on the maximum number of entries (rows) to be returned. The default is set to 100. The returned list may be smaller than the maximum, but will never be greater. When kept constant and used in combination with start, this field assists in pagination.

start

A zero-indexed positive integer denoting the start position of the first entry in the returned list. When used with max_rows, you can seek, slice, and paginate through the data set.

Defaults to 0, since entries are stored in a zero-indexed array. Meaning the first n entries will occupy indices 0...n-1.

Examples:

First page: http://localhost:8000/sheets/base?max_rows=100&start=0

Second Page: http://localhost:8000/sheets/base?max_rows=100&start=100

One result: http://localhost:8000/sheets/base?max_rows=1&start=0