australian statistics api specification · seng3011 api spec page 3 figure 1 shows how a system...
TRANSCRIPT
![Page 1: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/1.jpg)
SENG3011APISpec
Page1
AustralianStatisticsAPISpecification
Version: 1.2DateModified: 23March2017
![Page 2: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/2.jpg)
SENG3011APISpec
Page2
Thecontext.....................................................................................................................................2
FunctionsoftheAPI.......................................................................................................................2
2.1 RetailTradeAPI..........................................................................................................................2
InputParametersforAPI................................................................................................................3
OutputSpecificationfortheAPI.....................................................................................................4
4.1ForRetailStatisticsArea...............................................................................................................4
4.2ForMerchandiseExportArea.......................................................................................................4
AcquiringthedatafortheAPI........................................................................................................5
5.1RetailData....................................................................................................................................5
5.2MerchandiseExportData.............................................................................................................6
Appendix........................................................................................................................................8
6.1 AdditionalInformation:..............................................................................................................8
6.2 SampleOutputFormatforRetail...............................................................................................9
6.3 SampleOutputFormatforMerchandiseExport......................................................................10
6.4 References:...............................................................................................................................11
ThecontextWe are a company specialising in wide array of trading related services. We are developing acomplex system toprovide an analytics platform for our traders.Wewish to openour system tothirdpartysoftwarehouses,offering themability to“plug-in” independentsoftwaremodules thatimplement particular functions. We therefore request all interested companies to provide anindependentsoftwaremodulethatimplementsanAPIasspecifiedintherestofthisdocument.
FunctionsoftheAPI
2.1 RetailTradeAPIFor certain functionalities of our platform,we require industry data, statistics related to differentareas – specifically the monthly retail turnover by various industry groups or monthly value ofvariouscommoditiesthatareexported.FurtherwemaywantdataforvariousregionsofAustralia.
Australian Statistics API will receive a request from a third party software specifying an area ofstatistics, a list of regions, a list of categories (industries or commodities) and a period of timespecified by start and end date. The API should return the statistics according to the area ofstatistics.Forthisapplicationtherearetwomainareas:“Retail” and “MerchandiseExports”.
• If user requests“Retail”, the API should return themonthlyretailturnoverofeachregionandeachcategory,forthespecifiedperiodoftime.
• If the user requested “MerchandiseExports” as the statistics area, monthly value of each commodity listed in the categories, for each region and for defined time period, should be returned.
![Page 3: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/3.jpg)
SENG3011APISpec
Page3
Figure1showshowasystemwouldinteractwiththeAustralianStatisticsAPI.
Figure1-Highlevelview
Theprogramminglanguageinwhichthemoduleistobewrittenisnotimportantaslongasthereissomewaytoinvokeitfromoursystem.TheoutputoftheAustralianStatisticsAPIshouldbeaJSONfilecontainingdataintheformatspecifiedbelow.Itisimportantthatthemodulecanbeusedwithoutitssourcecodebeingrevealed.
InputParametersforAPITheAPIwedevelopshouldbeabletotakefourinputsasdefinedbyfollowingtable.
Parameter ArgumentsandFormatsStatisticsArea A string which can take value “Retail” or “MerchandiseExports”.State Alistofoneormoreregions(AUS,NSW,WA,SA,ACT,VIC,TAS,
QLD,NT)separatedby“,”.Category If StatisticsAria is “Retail”,alistofoneormoreindustry(Total,
Food, HouseholdGood, ClothingFootwareAndPersonalAccessory, DepartmentStores, CafesResturantsAndTakeawayFood, Other) separatedby“,”.ORIf StatisticsAria is “MerchandiseExports”,alistofoneormorecommoditiesofinterestfrom(Total,FoodAndLiveAnimals,BeveragesAndTobacco,CrudMaterialAndInedible,MineralFuelLubricentAndRelatedMaterial,AnimalAndVegitableOilFatAndWaxes,ChemicalsAndRelatedProducts,ManufacutedGoods,MachineryAndTransportEquipments,OtherManucacturedArticles,Unclassified)separatedby“,”.
startDate IntheformatofYYYY-MM-DDendDate IntheformatofYYYY-MM-DD
Sys
tem
Statisticsarea,listofregions,alistofcategories,periodoftime
AustralianStatisticsAPI
Listofvaluesforeachcategoryandregionforgivenperiodoftime,accordingtotheareaofstatistics
![Page 4: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/4.jpg)
SENG3011APISpec
Page4
OutputSpecificationfortheAPI
4.1ForRetailStatisticsAreaThemoduleshouldreturnajsonfilewithdatarequestedbyuser,intheformatdefinedinAppendix6.2.
Theformatofoutputdatatypesshouldbeasfollows:
OutputParameter DataFormatRetailIndustry Stringvaluefrom(Total, Food,
HousholdGood, ClothingFootwareAndPersonalAccessory, DepartmentStores, CafesResturantsAndTakeawayFood, Other)
State Stringvaluefrom(AUS,NSW,WA,SA,ACT,VIC,TAS,QLD)
Date LastdayofeachmonthinYYYY-MM-DDformat.Turnover Afloatingpointvalue
4.2ForMerchandiseExportAreaThemoduleshouldreturnajsonfilewithdatarequestedbyuser,intheformatdefinedinAppendix6.3.
Theformatanddatatypesofoutputdatatypesshouldbeasfollows:
Parameter DataTypeCommodity Stringvaluefrom(Total,FoodAndLiveAnimals,BeveragesAndTobacco,
CrudMaterialAndInedible,MineralFuelLubricentAndRelatedMaterial,AnimalAndVegitableOilFatAndWaxes,ChemicalsAndRelatedProducts,ManufacutedGoods,MachineryAndTransportEquipments,OtheranucacturedArticles,Unclassified)
State Stringvaluefrom(AUS,NSW,WA,SA,ACT,VIC,TAS,QLD,NT)
Date LastdayofeachmonthinYYYY-MM-DDformat.Value Afloatingpointvalue
AnotheroutputoftheAPIisalogfilemustcontainthefollowinginformation:
• Developerteam• Modulenameandversion• Parameterspassed• Anindicationifexecutionhasbeensuccessfulorthereisanerror• Iferror,indicatethenatureoftheerror• Ifsuccessful,needtosupply
Ø StartdateandtimeofexecutionØ EnddateandtimeofexecutionØ Elapsedtime
![Page 5: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/5.jpg)
SENG3011APISpec
Page5
Ø Outputfilename
AcquiringthedatafortheAPITofulfiltheuserrequestaboutretailtrades,youwillneedtohaveadatasource.Forthis,youshouldusetheRESTAPIprovidedbyAustralianBureauofStatistics(ABS)(http://stat.data.abs.gov.au/#).
5.1RetailDataAmongthevariousdatasetstheyprovide,theAPIneedstheMonthlyRetailTurnoverbyIndustryGroup.ABSprovidedifferentmechanismsoffilteringandacquiringthedata–asexcelfiles,csvfilesoroveraRESTAPIURL.YoushouldusetheRESTAPIURLintheapplication,tofilterandacquiredatadynamically,tomatchwiththeparametersprovided.
TounderstandtheAPIanddatasetsyoucanvisitpage(http://stat.data.abs.gov.au/#)andnavigatetoINDUSRTY->RetailandWholesaleTrade->Retail->RetailTrade->MonthlyRetailTurnoverbyIndustryGroup
YoucancustomizethedatasetbychangingvariousparametersatSelectiontabasshowninfigureabove.Accordingtotheparametersyouchange,theURLcanbegeneratedatExportTab->DeveloperAPItab->GenerateAPIQuerybuttonURL:Export->DeveloperAPItab->GenerateAPIQuerybutton
ForourAPI,weareinterestedintheRegion,RetailIndustryTypeandTimeandFrequencyParameters.Otherparameterscanbeleftasfollows:
DataType:CurrentPrices($Million)AdjustmentType:Original
Forfurtherclarifications,givenbelowisasampleURL:
![Page 6: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/6.jpg)
SENG3011APISpec
Page6
http://stat.data.abs.gov.au/sdmx-json/data/RT/0+1+2.2.41+42+43.10.M/all?startTime=2015-01&endTime=2015-12&dimensionAtObservation=allDimensions ThehighlightedpartoftheURLcanbeusedtopassparameterstotheABSAPI.Ifweconsiderthepart“0+1+2.2.41+42+43.10.M”,eachcategoryofparameterisseparatedby“.”IntheorderofindexesoftheRegion,Indexofdatatype,IDforretailindustry,IDofadjustmenttypeandTime&Frequenceindicator.“+”signisusedtoseparatealistofattributespassedtooneparameter.FollowingtableexplainstheparameterspassedintheexampleURL.Exploretheparametersfurtherbyexploringthewebpage.
Parameter ReferredMeaning0+1+2 Requestdataforthreeregions(0:Australia,1:New
SouthWales,2:Victoria).Youcanusefrom0to8numbers.
2 Refertothedatatype(2-CurrentPrices($Million)).Youcankeepthisasdefault.
41+42+43 RefertoalistofIDsforretailindustry(20-Total,41-FoodRetailing,42-HouseholdGoodRetailing).Explorefurtherinwebpage.
10 RefertotheAdjustmenttype(10-Original).Youcankeepthisasdefault.
M RequestMonthlydatastartTime=2015-01&endTime=2015-12 Usedtodefinetheduration,forwhichdatais
requested. TheABSAPIwillreturndatasetasJSONfile,eachdatavalueindexedaccordingtotheparameters.TheindexingisdescribedattheendoftheJSONfile.YoucantypetheabovegivenURLonthebrowserandobservetheoutputformat.Thedatastructurecanbefoundinfollowinglink:
http://stat.data.abs.gov.au/restsdmx/sdmx.ashx/GetDataStructure/RT
5.2MerchandiseExportDataForMerchandiseExport,theAPIneedstheMonthlyValueofExportsbyCommodity.ABSprovidedifferentmechanismsoffilteringandacquiringthedata–asexcelfiles,csvfilesoroveraRESTAPIURL.YoushouldusetheRESTAPIURLintheapplication,tofilterandacquiredatadynamically,tomatchwiththeparametersprovided.
TounderstandtheAPIanddatasetsyoucanvisitpage(http://stat.data.abs.gov.au/#)andnavigatetoECONOMY -> International Trade -> Exports -> Merchandise Exports -> Key Figures, Exports by SITC
![Page 7: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/7.jpg)
SENG3011APISpec
Page7
YoucancustomizethedatasetbychangingvariousparametersatSelectiontabasshowninfigureabove.Accordingtotheparametersyouchange,theURLcanbegeneratedatExportTab->DeveloperAPItab->GenerateAPIQuerybuttonForourAPI,weareinterestedintheStateOfOrigin,CommoditybySITCandTimeandFrequencyParameters.Otherparameterscanbeleftasfollows:
Industry of origin - Total Country of destination – Total Forfurtherclarifications,givenbelowisasampleURL:
http://stat.data.abs.gov.au/sdmx-json/data/MERCH_EXP/-+1+2+9+F.0+1+2+3+4+5+6+7+8+9.-1.-.M/all?startTime=2015-01&endTime=2015-12&dimensionAtObservation=allDimensions ThehighlightedpartoftheURLcanbeusedtopassparameterstotheABSAPI.Ifweconsiderthepart“-+1+2+9+F.0+1+2+3+4+5+6+7+8+9.-1.-.M”,eachcategoryofparameterisseparatedby“.”IntheorderofIDsforlistofStateofOrigin,ListofCommodity by SITC, List of Industry of Origin, List of Country of Destination andTime&Frequencyindicator.“+”signisusedtoseparatealistofattributespassedtooneparameter.FollowingtableexplainstheparameterspassedintheexampleURL.Exploretheparametersfurtherbyexploringthewebpage.
Parameter ReferredMeaning-+1+2 RequestdataforState of Origin (- : total, 1 : New
South Wales) Find IDs for other states using the ABS web site.
-1+0 Refertothecommodity by SITC (-1:Total, 0 - Food and Live Animals ) Find IDs for other commodities using the ABS web site.
![Page 8: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/8.jpg)
SENG3011APISpec
Page8
-1 Refertotheindustryoforigin.Keep–1asdefaulttoconsideralltheindustries.
- Refertothecountryofdestination.Keep–asdefaulttoindicatetotalofexports.
M RequestMonthlydatastartTime=2015-01&endTime=2015-12 Usedtodefinetheduration,forwhichdatais
requested. TheABSAPIwillreturndatasetasJSONfile,eachdatavalueindexedaccordingtotheparameters.TheindexingisdescribedattheendoftheJSONfile.ExamplefiletypethegivenURLinthebrowserandobservetheresultsreturned.
Appendix
6.1 AdditionalInformation:Teamshavethechoiceofrunningtheirsystemontwodifferentplatforms:
• StandaloneProgram
§PCrunningWindows
§Unix/Linuxplatform
• Webservice(accessibleviaaRESTinterface)
Throughouttheworkshop,eachteamwillneedtohaveaWebpage.Asaminimum,thepageisshowing:
• Theteamnameandmembers• Consecutivereleasesoftheirmodule.Eachreleasepagemustincludealinktodownloadthe
moduleandinformationabout:
o Thedateandversionoftherelease
o Whathasbeenimplementedsofar
o Differenceswithpreviousversion
o Clearinstructionsonhowtorunthemoduleinstandalonemode
o Guidelinesonhowtointegratethemodulewithothersystems
o Anytestsoftwareordata
![Page 9: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/9.jpg)
SENG3011APISpec
Page9
6.2 SampleOutputFormatforRetail
{"MonthlyRetailData":[ {“RetailIndustry”:<>, “RegionalData”:[
{State:<>, Data:[
{“Date”:<>,“Turnover”:<>}{“Date”:<>,“Turnover”:<>}]}{State:<>,
Data:[{“Month”:<>,“Turnover”:<>}{“Month”:<>,“Turnover”:<>}]}]
} {“RetailIndustry”:<>, “RegionalData”:[
{State:<>, Data:[
{“Date”:<>,“Turnover”:<>}{“Date”:<>,“Turnover”:<>}]}{State:<>,
Data:[{“Date”:<>,“Turnover”:<>}{“Date”:<>,“Turnover”:<>}]}]
}]}
![Page 10: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/10.jpg)
SENG3011APISpec
Page10
6.3 SampleOutputFormatforMerchandiseExport
{"MonthlyCommodityExportData":[ {“Commodity”:<>, “RegionalData”:[
{State:<>, Data:[
{“Date”:<>,“Value”:<>}{“Date”:<>,“Value”:<>}]}{State:<>,
Data:[{“Date”:<>,“Value”:<>}{“Date”:<>,“Value”:<>}]}]
} {“Commodity”:<>, “State”:[
{Region:<>, Data:[
{“Date”:<>,“Value”:<>}{“Date”:<>,“Value”:<>}]}{State:<>,
Data:[{“Date”:<>,“Value”:<>}{“Date”:<>,“Value”:<>}]}]
}]}
![Page 11: Australian Statistics API Specification · SENG3011 API Spec Page 3 Figure 1 shows how a system would interact with the Australian Statistics API. Figure 1 - High level view The programming](https://reader035.vdocuments.mx/reader035/viewer/2022080721/5f7a851444c4d1370e676045/html5/thumbnails/11.jpg)
SENG3011APISpec
Page11
6.4 References:[1]ABS.Stat:http://stat.data.abs.gov.au/#