australian statistics api specification · seng3011 api spec page 3 figure 1 shows how a system...
TRANSCRIPT
SENG3011APISpec
Page1
AustralianStatisticsAPISpecification
Version: 1.2DateModified: 23March2017
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.
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
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
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:
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
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.
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
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”:<>}]}]
}]}
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”:<>}]}]
}]}
SENG3011APISpec
Page11
6.4 References:[1]ABS.Stat:http://stat.data.abs.gov.au/#