Tigo REST API V3 - Tigo Energy · This api is used to work with the Tigo Energy platform to...

/31 ProvidedbyTigo.©Copyright2019byTigoEnergy,Inc.

TigoRESTAPIV3IntroductionThisapiisusedtoworkwiththeTigoEnergyplatformtoautomatetheretrievalandcreationofelements.ItwillattempttoadheretostandardRESTcallsfoundinmostRESTimplementations.Parties

Server-TheTigoplatformandurlsassociatedwiththeapiClient-ThirdpartyuserwithapiaccesstotheTigoplatformand/orTigoapi.

DataTransferAllinputandresponseswillbeinJSONformat.Additionalvaluesmaybeaddedatanytimebutwillnotaffectpreviousfunctionalityunlessstatedotherwise.

BaseURLhttps://api2.tigoenergy.com/api/v3/

ProtocolsGET-Willbeusedwhenyouwanttoretrieveinformationfromtheserver.POST-WillbeusedtocreatenewitemsPATCH/PUT-WillbeusedtoupdateinformationDELETE-Willbeusedtodeleteorremoveitems

AuthorizationThev3apiimplementsanauthtokensystem.ThisallowsyoutouseatokentoauthenticateendpointsontheTigoplatform.

ThepreferredmethodofauthenticationisusingaheaderwithaheaderAuthorizationtag.

YoucangainanaccesstokenusingBasicAuthwiththeLoginendpointlistedbelow.

Example:

Authorization:BearerABCDE

CurlExample:

curl-H"Authorization:BearerABCDE""https://api2.tigoenergy.com/api/v3/<endpoint>"

HTTPErrorCodesCodeDescription

2xxSuccess


3xxConnectionchangesorissues4xxClientissue5xxServerissue

ErrorResponse

AjsonerrorresponsemaybeaccompaniedwithHTTPcodes

{"name":"Unauthorized","message":"Youarerequestingwithaninvalidcredential.","code":0,"status":401}

ReturnHeader&RateLimitingItisgoodpracticetopayattentiontoheaderssincetheymayreturnadditionalinformationaboutyourrequest.SomeexamplesincluderatelimitingofapicallsoradditionalinformationabouttheintendedAPIendpoint.

X-Rate-Limit-LimitMaxlimitinnumberofrequestsX-Rate-Limit-RemainingRemainingnumberofrequestsX-Rate-Limit-ResetNumberofsecondstilllimitresetX-System-Config-UpdateTimestampoflastconfigupdate,whensystemidisspecified

NoteaboutdocumentCopyandpastingfromthisdocumentmayplacetheimproperquotes""whenrunningcommands.Ifsomethingisnotworkingpleasecheckthequotesfirst.


GETLoginLoginandgetanauthorizationtokenanduser_id.Thisusesbasicauthtosendtheusernameandpassword.

ExampleCallGEThttps://api2.tigoenergy.com/api/v3/users/login

CURLExamplecurl-v-u"{username}:{password}""https://api2.tigoenergy.com/api/v3/users/login"

ResponseParametersName Type Description

user Envelope Containerobjectforuser

user.user_id Integer idoftheruserlogin

user.auth String AuthstringforOauthauthentication

user.expires ISO8601 Timeoutofauthorization

user.user_type String Typeofuser"Basic","Installer","Partner"

ExampleResponse200OK

{"user":{"user_id":1,"auth":"ABCDE","expires":"2016-09-01T00:00:00-08:00","user_type":"Basic",}}


GETLogoutLogoutthecurrentuserauthtoken.Thiswillmaketheauthtokennolongervalid.

ExampleCallGEThttps://api2.tigoenergy.com/api/v3/users/logout

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/users/logout"-H"Authorization:BearerABCDE"


{"name":"OK","message":"Loggedoutuser","code":0,"status":200}


GETusers/getListthecurrentuser.Willonlybeabletoquerycurrentlyloggedinuser.

ExampleCallsGEThttps://api2.tigoenergy.com/api/v3/users/1GEThttps://api2.tigoenergy.com/api/v3/users/get?id=1

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/users/1"-H"Authorization:BearerABCDE"

GETParametersName Type Description

*id Integer IDoftheuser.

*Requiredfield


user Envelope Objectcontainerofuser

user.user_id Integer IDoftheuser

user.login String Loginofuser

user.first_name String Firstnameofuser

user.last_name String Lastnameofuser

user.email String Emailofuser

user.company String Associatedcompanyofuser

user.street String Streetaddressofuser

user.street2 String Street2addressofuser

user.city String Cityofuser


user.state String Stateofuser

user.zip Integer Zipofuser

user.country String Countryofuser

user.mobile String Mobilephoneofuser

user.user_type String Usertypeofuser

user.avatar String URLofavatar


{"user":{"user_id":1,"login":"1","first_name":"John","last_name":"Smith","email":"[email protected]","company":"Tigo","street":"123FakeSt.","city":"Fakertown","state":"CA","zip":"123456","country":"UnitedStates","mobile":"1231231234","user_type":"Basic"}}


GETsystems/listListthecurrentsetofsystemsyouhaveaccesstoo.

ExampleCallsGEThttps://api2.tigoenergy.com/api/v3/systemsGEThttps://api2.tigoenergy.com/api/v3/systems?limit=50

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/systems"-H"Authorization:BearerABCDE"


page Integer Pagetodisplayofsystems

limit Integer Numberofsystemstolist

sort Integer FieldtosortonDefault:system_id


systems Object Objectcontainerofsystems.

systems.system_id Integer IDofthesystem.

systems.created ISO8601 Datetimeofsystemcreation.

systems.name String Nameofsystem.

systems.external_id String Useforexternaluse.

systems.street String Address.

systems.city String City.

systems.state String StateorRegion.


systems.zip String Zip.

systems.country String Country.

systems.latitude Float Latitudecoordinates.

systems.longitude Float Longitudecoordinates.

systems.timezone String UnixTimezone.

systems.turn_on_date ISO8601Date Dateplannedturnon.Example:YYYY-MM-DD

systems.power_rating Float MaxDCpowerratingofsystem.


{"systems":[{"created":"2014-05-16T20:50:45+00:00","city":"PO123","company":"OneCoolDude","contact_name":"JohnSmith","country":"UnitedStates","external_id":"test","system_id":1,"latitude":12.3456789,"longitude":12.3456789,"name":"TestSystem","power_rating":12000,"state":"FakerCity","street":"123FakeStreet","zip":"12345","turn_on_date":"null"},{"created":"2014-05-16T20:50:45+00:00","city":"PO123","company":"OneCoolDude","contact_name":"JohnSmith","country":"UnitedStates","external_id":"test2","system_id":2,"latitude":12.3456789,"longitude":12.3456789,"name":"TestSystem","power_rating":12000,"state":"FakerCity","street":"123FakeStreet","zip":"12345","turn_on_date":"2017-01-01"


}]}


GETsystems/viewGetasinglesystemyouhaveaccessto

ExampleCallGEThttps://api2.tigoenergy.com/api/v3/systems/1GEThttps://api2.tigoenergy.com/api/v3/systems/view?id=1

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/systems/view?id=1"-H"Authorization:BearerABCDE"


*id Integer SystemIDofthesystem

include String Sideloadassociatedenvelope

*Requiredfield

AdditionalIncludesName Type Description

inverters Envelope[] Invertersforsystem

mppts Envelope[] Mpptsforsystem

strings Envelope[] Stringsforsystem

panels Envelope[] Panelsforsystem

meters Envelope[] Metersforsystem

objects Envelope[] Objectsforsystem

images Envelope[] Imagesforsystem

sources Envelope[] Sourcesforsystem



system Object Objectcontainerofsystem.

system.system_id Integer IDofthesystem.

system.created ISO8601 Datetimeofsystemcreation.

system.name String Nameofsystem.

system.external_id String Useforexternaluse.

system.street String Address.

system.city String City.

system.state String StateorRegion.

system.zip String Zip.

system.country String Country.

system.latitude Float Latitudecoordinates.

system.longitude Float Longitudecoordinates.

system.timezone String UnixTimezone.

system.turn_on_date ISO8601Date Dateplannedturnon.Example:YYYY-MM-DD

system.power_rating Float MaxDCpowerratingofsystem.


{"system":{"created":"2014-05-16T20:50:45+00:00","city":"PO123","company":"OneCoolDude","contact_name":"JohnSmith","country":"UnitedStates","external_id":"test",


"system_id":1,"latitude":12.3456789,"longitude":12.3456789,"name":"TestSystem","power_rating":12000,"state":"FakerCity","street":"123FakeStreet","zip":"12345","turn_on_date":"2017-01-01",}}


GETsystems/layoutReturnstheelectricalconfigurationofthesystem.

ExampleCallsGEThttps://api2.tigoenergy.com/api/v3/systems/layout?id=1

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/systems/layout?id=1"-H"Authorization:BearerABCDE"

GETParameterName Type Description

*id Integer IDofthesystem.

*Requiredfield


{"system":{"system_id":1,"inverters":[{"inverter_id":1,"inverter_type_id":1,"label":"Inverter1","object_id":1,"inverter_serial":"ABC","mppts":[{"mppt_id":1,"label":"MPPT1","strings":[{"string_id":1,"label":"StringA","short_label":"A","object_id":2,"panels":[{"panel_id":1,"label":"A1","short_label":1,"serial":"O4C05B8001234",


"type":"TS4-S","source_id":1,"object_id":3,"panel_type_id":1}]}]}]}]}}


GETobjects/systemListtheobjectsavailabletoquerydatafrom.Thismaybedifferentfromsystem/layout.

ExampleCallGEThttps://api2.tigoenergy.com/api/v3/objects/system?system_id=1

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/objects/system?system_id=1"-H"Authorization:BearerABCDE"


*system_id Integer Required,theIDofthesystem

*Requiredfield


objects Envelope[] Containerobjectofobjects.

objects.id Integer IDoftheobject.

objects.label String Thenameoftheobject.

objects.object_type_id Integer Thetypeoftheobject.

objects.parent_id Integer Theparentidoftheobject.-1signalstherootobject.

objects.datasource String Thekeyusedtoreferencethedata.

objects.children Array Arrayofobjectidsforallthechildrenobjects.

objects.ui Object


Attributesoftheuidisplay;X:xpositionY:ypositionMP:MaxPowerRatingLabel:additionlabelX1,X2,Y1,Y2:CoordinateforalinesegmentDR:MinutestodatarepeatZ:Zoomlevelorscale


{"objects":[{"id":1,"label":"System","object_type_id":1,"parent_id":-1,"datasource":null,"children":[2,5],"ui":{"X":100,"Y":100,"MP":5000}},{"id":2,"label":"StringA","object_type_id":3,"parent_id":1,"datasource":null,"children":[3]},{"id":3,"label":"A1","object_type_id":2,"parent_id":2,"datasource":"04C05B800ACE.panels.A1","children":[3],"ui":{"X":150,"Y":150}}


]}


GETobjects/typesListstheavailableobjecttypes

ExampleCallGEThttps://api2.tigoenergy.com/api/v3/objects/types

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/objects/types"-H"Authorization:BearerABCDE"


object_types Envelope[] Containerobjectofobjecttypes.

object_types.object_type_id Integer IDoftheobjecttype.

object_types.label String Descriptionoftheobjecttype.


{"object_types":[{"object_type_id":1,"label":"System"},{"object_type_id":2,"label":"Panel"},{"object_type_id":3,"label":"String"}]}


GETsources/systemDisplayallofasystem'ssources

ExampleCallGEThttps://api2.tigoenergy.com/api/v3/sources/system?system_id=1

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/sources/system?system_id=1"-H"Authorization:BearerABCDE"


*system_id Integer Required,theIDofthesystem

*Requiredfield


sources Envelope[] Containerobjectofsources.

sources.source_id Integer IDofthesource.

sources.name String Thenameofthesource.

sources.serial String TheMACaddressofthesource.

sources.gateway_count Integer TheNumberofgatewaysreportingtothissource.

sources.control_state Integer ThecurrentstateofPVOffonthesystem.

sources.last_checkin ISO8601 Thedateofthelasttimethesourcereportedintotheserver.

sources.timezone String Thetimezoneinwhichthesourceislocated.

sources.sw_version String Thesoftwareversionrunningonthesource.

sources.created_on ISO8601Date Thedatethesourcewascreated.


sources.sets Envelope[] Containerobjectforsets

sources.sets.set_name String Thenameofthedataset.

sources.sets.last_min ISO8601Date Thelatestminuteofdataforthedataset.

sources.sets.last_day ISO8601Date Thelatestdayofdataforthedataset.

sources.system_id Integer IDofthesystem.


{"sources":[{"source_id":9999,"name":"MyCloudConnect","serial":"04C05B8FFFFF","gateway_count":1,"created_on":"2014-07-29T16:19:26-07:00","control_state":"on","last_checkin":"2017-02-16T23:19:06-08:00","timezone":"America/Los_Angeles","sw_version":"ffs-2.4.0-image.img","sets":[{"set_name":"panels_avg","last_min":"2016-09-07T18:32:00-07:00","last_day":"2014-11-18T00:00:00-08:00"},{"set_name":"Wattnode","last_min":"2014-09-09T14:06:00-07:00","last_day":"2014-09-08T00:00:00-07:00"}],"system_id":11},{"source_id":1010,"name":"MyCloudConnect2","serial":"04C05B8EFFFF","gateway_count":1,"created_on":"2014-07-29T16:19:26-07:00","control_state":"on","last_checkin":"2017-02-16T23:19:06-08:00","timezone":"America/Los_Angeles","sw_version":"ffs-2.4.0-image.img","sets":[{"set_name":"panels_avg","last_min":"2016-09-07T18:32:00-07:00","last_day":"2014-11-18T00:00:00-08:00"


}],"system_id":11}]}


GETdata/aggregateReturnminuteanddaylevelaggregates

ExampleCallsGEThttps://api2.tigoenergy.com/api/v3/data/aggregate

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/data/aggregate?system_id=1&start=2017-01-01T00:00:00&end=2017-01-01T23:59:59&level=min&param=Vin"-H"Authorization:BearerABCDE"


*system_id Integer IDofthesystem

*start ISO8601 StarttimeofdataExample:"2018-01-01T00:00:00"

*end ISO8601 EndtimeofdataExample:"2018-01-01T23:59:59"

level String TypeofaggregationDefault:"min""day"

sensors String WhethertoincludesensordataDefault:"true""false"

param String TypeofdatatoreturnDefault:"Pin","Vin","Iin","RSSI"

object_ids String CommalistofidsDefault:all"1,2,3"

header String TypeofheadertoreturnDefault:"id""key"

*Requiredfields

Notes

P=power,V=voltage;inasPindefinedpowerfromthepanelMinuteleveldatawillbeshownasWattsforPin


DayleveldatawillbeshownasEnergyforPinNoteheadercanchangeinthisformatunlessobject_idsspecified


Withidheader

Datetime,1,2,32014/09/2300:06:23,23,23,232014/09/2300:06:24,23,23,232014/09/2300:06:25,23,23,232014/09/2300:06:26,23,23,232014/09/2300:06:27,23,23,232014/09/2300:06:28,23,23,23Datetime,1,22014/09/2300:06:28,23,23

Withkeyheader

Datetime,04C05B800ACE.panels.A1_Vin,04C05B800ACE.panels.A2_Vin2014/09/2300:06:23,23,232014/09/2300:06:24,23,232014/09/2300:06:25,23,232014/09/2300:06:26,23,232014/09/2300:06:27,23,232014/09/2300:06:28,23,23Datetime,04C05B800ACE.panels.A1_Vin2014/09/2300:06:28,23


GETdata/combinedWetypicallyhavedatacominginaspanelleveldata.Wethencombinethedatatopresentatdifferentlevelsofthesystem.Anexamplewouldbetheentiresystemoraparticularstring.Thisendpointwillautomaticallycombinethedataintoasinglenumberforeachobjectid.

ExampleCallsGEThttps://api2.tigoenergy.com/api/v3/data/combined?system_id=1&agg=hour&start=2016-09-07&end=2017-09-07

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/data/combined?system_id=1&agg=hour&start=2016-08-16T08:00:00&end=2017-08-16T08:03:00&objects_ids=1,2"-H"Authorization:BearerABCDE"



level String LevelofdatatocombineLongname:"minute","hour","day","month","year"Shortname:"mi","h","h","m","y"

start ISO8601 StarttimeofdataExample:"2018-01-01T00:00:00"

end ISO8601 EndtimeofdataExample:"2018-01-01T23:59:59"

object_ids String Eachidwillbethecombinationofchildids.Defaultissystemlevel"1,2,3"

*Requiredfield

Notes

MinuteleveldatawillbeshownasWattsGreaterthanminuteleveldatawillbeshownasWattHoursAggregationabovehourwillsettimeforstart00:00:00andend23:59:59Softlimitsondatarangesareenforced,anerrorwillreturnifitistoolargeofarange.



DATETIME,1,22016/08/1608:00:00.000,1170,352016/08/1608:01:00.000,1175,362016/08/1608:02:00.000,1195,382016/08/1608:03:00.000,1216,50


GETdata/summaryGetsomebasicinformationfromasystem.

ExampleCallsGEThttps://api2.tigoenergy.com/api/v3/data/summary?system_id=1

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/data/summary?system_id=1"-H"Authorization:BearerABCDE"



*Requiredfield


summary Envelope Containerobjectforsummary.

summary.lifetime_energy_dc Float LifetimeDCenergyinWattHours.

summary.ytd_energy_dc Float Year-to-dateDCenergyinWattHours.

summary.daily_energy_dc Float DailyDCenergyinWattHours.

summary.last_power_dc Float LastpoweroutputinWatts.

summary.updated_on ISO8601 Datetimeoflastupdate.


{"summary":{"lifetime_energy_dc":18607879.27,"ytd_energy_dc":500.32,


"daily_energy_dc":0,"updated_on":"2014-11-18T00:00:00-08:00","last_power_dc":0}}


GETalerts/systemGetallthealertsforthegivensystem

ExampleCallGEThttps://api2.tigoenergy.com/api/v3/alerts/system?system_id=1

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/alerts/system?system_id=1"-H"Authorization:BearerABCDE"


*system_id Integer Systemidtoaccessalerts.

language String Languageofthealerttodisplay.

start_added ISO8601 Starttimetofilteralerts.

end_added ISO8601 Endtimetofilteralerts.

page Integer Pageofalertstofilter.

limit Integer Numberofitemstofilter.

*Requiredfield


alerts Envelope[] Objectcontainerofalerts.

alerts.alert_id Integer Uniquealertid.

alerts.added ISO8601 Whenthealertwasadded.

alerts.generated ISO8601 Whenthealertwasadded.

alerts.system_id Integer IDofthesystem.

alerts.unique_id Integer Uniquealertcode.

alerts.title String Titleofthealert.

alerts.message String Detailsofthemessage.

alerts.description String Detaileddescriptionofthealert.


{"alerts":[{"alert_id":1,"added":"2018-08-01T09:09:05-07:00","generated":"2018-08-01T09:08:20-07:00","system_id":1,"unique_id":106,"title":"TigoAlert:StringShutdown","message":"StringID:\n-StringF(2018-07-3114:22,2018-07-3114:42,2018-07-3114:57)\n-StringG(2018-07-3114:22,2018-07-3114:42,2018-07-3114:57)\n-StringH(2018-07-3114:22,2018-07-3115:08)","description":"YourTigosystemhasdetectedastringofPVmodulesthathasshutdown.TroubleshootingSteps:<ol><li>Verifythatyourinverterison.</li><li>Checkforanyerrorcodesontheinverter.(Formoreinformationaboutyourinvertererrorcodes,pleasecontactyourinstallerorinvertercompany.)</li></ol>WhatdoesthisAlertmean:Thiscouldbeduetoasystemhardwareissue.Contactyourinstallerorinvertercompanyaboutaninvertererrorcodes.Ifyouhaveanyadditionalquestions,please<ahref=\"https://www.tigoenergy.com/contacts/\">contact</a>Tigo'sSupportTeam."},]}

GETalerts/typesListallthealerttypes

ExampleCallGEThttps://api2.tigoenergy.com/api/v3/alerts/types

CURLExamplecurl-v"https://api2.tigoenergy.com/api/v3/alerts/types"-H"Authorization:BearerABCDE"


language String LanguageCodeString.Default:ENDE,EL,EN,ES,FR,IT,JP,KO


alert_types Envelope[] Containerobjectofalerttypes.

alert_types.alert_type_id Integer IDofthealerttypes.

alert_types.title String Shortdescriptionofthealert.

alert_types.description String InformationandResolutionofalert.

alert_types.unique_id Integer Uniqueidusedtoreferencecodes.


{"alert_types":[{"alert_type_id":24,"description":"YourTigosystemhasdetectedaPVmodulewithlowenergyproduction.TroubleshootingSteps:","title":"TigoAlert:LowPowerProductiononPVModule","unique_id":300

},{"alert_type_id":25,"description":"YourTigosystemhasdetectedastringofPVmoduleswithlowenergyproduction.TroubleshootingSteps:","title":"TigoAlert:LowPowerProductiononPVString","unique_id":301}]}

Tigo REST API V3 - Tigo Energy · This api is used to work with the Tigo Energy platform to...

Documents

Transcript of Tigo REST API V3 - Tigo Energy · This api is used to work with the Tigo Energy platform to...