Package: grndwork-api-client
Groundwork API ClientAPI client forGroundWork RenewablesInstallationJavaScript:$ npm install @grndwork/api-clientPython:$ pip install grndwork-api-clientUsageJavaScript:import{createClient}from'@grndwork/api-client';constclient=createClient();Python:fromgrndwork_api_clientimportcreate_clientclient=create_client()In order to accesshttps://api.grndwork.comyou must first obtain a refresh token from GroundWork Renewables.The path to this file can be provided to the client using theGROUNDWORK_TOKEN_PATHenvironment variable.Or the subject and token values from this file can be provided using theGROUNDWORK_SUBJECTandGROUNDWORK_TOKENenvironment variables.When providing subject and token valuesGROUNDWORK_TOKEN_PATHmust not be set.Javascript ClientFor methods that return lists, the javascript client returns a custom async iterable. You can consume this using:forawait(conststationofclient.getStations()){...}orconststations=awaitclient.getStations().toArray();Python ClientFor methods that return lists, the python client returns a standard iterator. You can consume this using:forstationinclient.get_stations():...orstations=list(client.get_stations())APIGet StationsJavaScript:client.getStations(query?:GetStationsQuery,pageSize:number=100):IterableResponse<Station>Python:client.get_stations(query:GetStationsQuery=None,*,page_size:int=100)->Iterator[Station]Takes an optional get stations query object as an argument and returns an array of stations.Get Stations Query ParametersParamTypeDescriptionstationstringOnly return stations with UUID, name, or name matching patternsitestringOnly return stations for site with UUID, name, or name matching patternclientstringOnly return stations for client with UUID, name, or name matching patternlimitnumberOnly return a limited number of stationsoffsetnumberNumber of stations to skip over before returning resultsPattern MatchingParameters that support patterns can use a wildcard*at the beginning and/or end of the string.Pattern matching is case insensitive.For example:JavaScript:conststations=awaitclient.getStations({station:'Test*'}).toArray();Python:stations=list(client.get_stations({'station':'Test*'}))Would return all stations whose name starts withTest.Page SizeYou can set an optional page size to control the number of stations returned per request from the API.
( min: 1, max: 100, default: 100 )JavaScript:conststations=awaitclient.getStations({},50).toArray();Python:stations=list(client.get_stations({},page_size=50))Return ValuesStations are returned in alphabetical order by station name.Sample Output[{"client_uuid":"286dfd7a-9bfa-41f4-a5d0-87cb62fac452","client_full_name":"TestClient","client_short_name":"TEST","site_uuid":"007bb682-476e-4844-b67c-82ece91a9b09","site_full_name":"TestSite","station_uuid":"9a8ebbee-ddd1-4071-b17f-356f42867b5e","station_full_name":"TestStation","description":"","latitude":0,"longitude":0,"altitude":0,"timezone_offset":-5,"start_timestamp":"2020-01-01 00:00:00","end_timestamp":"2020-12-31 23:59:59","data_file_prefix":"Test_","data_files":[{"filename":"Test_OneMin.dat","is_stale":false,"headers":{"columns":["Ambient_Temp"],"units":["Deg_C"],"processing":["Avg"]}}]}]Get DataJavaScript:client.getData(query?:GetDataQuery,pageSize:number=100):IterableResponse<DataFile>Python:client.get_data(query:GetDataQuery=None,*,page_size:int=100)->Iterator[DataFile]Takes an optional get data query object as an argument and returns an array of data files.Get Data Query ParametersParamTypeDescriptionfilenamestringOnly return data files with name or name matching patternstationstringOnly return data files for station with UUID, name, or name matching patternsitestringOnly return data files for site with UUID, name, or name matching patternclientstringOnly return data files for client with UUID, name, or name matching patternlimitnumberOnly return a limited number of filesoffsetnumberNumber of files to skip over before returning resultsrecords_limitnumberNumber of records to return per file ( min: 0, max: 1500, default: 0 )records_beforetimestampOnly return records at or before timestamp ( format:yyyy-mm-dd hh:mm:ss)records_aftertimestampOnly return records at or after timestamp ( format:yyyy-mm-dd hh:mm:ss)Pattern MatchingParameters that support patterns can use a wildcard*at the beginning and/or end of the string.Pattern matching is case insensitive.For example:JavaScript:constdataFiles=awaitclient.getData({filename:'*_OneMin.dat'}).toArray();Python:data_files=list(client.get_data({'filename':'*_OneMin.dat'}))Would return all one minute data files.Page SizeYou can set an optional page size to control the number of files returned per request from the API.
( min: 1, max: 100, default: 100 )JavaScript:constdataFiles=awaitclient.getData({},50).toArray();Python:data_files=list(client.get_data({},page_size=50))Return ValuesData files are returned in alphabetical order by filename.Whenrecords_limitis included in the query, records are returned in reverse chronological order starting at the most recent timestamp.
Whenrecords_limitis greater then 1, only a single data file will be returned per request ( equivalent to page size of 1 ).For example:JavaScript:constdataFiles=awaitclient.getData({limit:1,records_limit:100}).toArray();Python:data_files=list(client.get_data({'limit':1,'records_limit':100}))Would return the most recent 100 records from the first file alphabetically.Sample Output[{"source":"station:9a8ebbee-ddd1-4071-b17f-356f42867b5e","filename":"Test_OneMin.dat","is_stale":false,"headers":{"columns":["Ambient_Temp"],"units":["Deg_C"],"processing":["Avg"]},"records":[{"timestamp":"2020-01-01 00:00:00","record_num":1000,"data":{"Ambient_Temp":50}}]}]Post DataJavaScript:client.postData(payload:PostDataPayload):Promise<void>Python:client.post_data(payload:PostDataPayload)->NoneTakes a post data payload object as an argument and uploads it to the cloud.Post Data PayloadParamTypeDescriptionsourcestringThe station that collected the datafilesArrayArray of data files ( min length: 1, max length: 20 )files[].filenamestringFilename using the format `<OneMinfiles[].headersDataFileHeadersOptional headers for the filefiles[].headers.metaRecord<string, string>User defined meta data for the filefiles[].headers.columnsArrayArray of column names matching the data keysfiles[].headers.unitsArrayArray of units for the columnsfiles[].headers.processingArrayArray of processing used for column data (Min, Max, Avg)files[].recordsArrayArray of data records for file ( max length: 100 combined across all files )files[].records[].timestamptimestampThe timestamp of the data record in UTC ( format:yyyy-mm-dd hh:mm:ss)files[].records[].record_numnumberPositive sequential number for records in filefiles[].records[].dataRecord<string, any>Data for record, keys should matchheader.columnsoverwritebooleanWhether to overwrite existing data records when timestamps match