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/#