Australian Statistics API Specification

Transcription

1 Australian Statistics API Specificatin Versin: 1.2 Date Mdified: 23 March 2017 Page 1

2 The cntext... 2 Functins f the API Retail Trade API... 2 Input Parameters fr API... 3 Output Specificatin fr the API Fr Retail Statistics Area Fr Merchandise Exprt Area... 4 Acquiring the data fr the API Retail Data Merchandise Exprt Data... 6 Appendix Additinal Infrmatin: Sample Output Frmat fr Retail Sample Output Frmat fr Merchandise Exprt References: The cntext We are a cmpany specialising in wide array f trading related services. We are develping a cmplex system t prvide an analytics platfrm fr ur traders. We wish t pen ur system t third party sftware huses, ffering them ability t plug-in independent sftware mdules that implement particular functins. We therefre request all interested cmpanies t prvide an independent sftware mdule that implements an API as specified in the rest f this dcument. Functins f the API 2.1 Retail Trade API Fr certain functinalities f ur platfrm, we require industry data, statistics related t different areas specifically the mnthly retail turnver by varius industry grups r mnthly value f varius cmmdities that are exprted. Further we may want data fr varius regins f Australia. Australian Statistics API will receive a request frm a third party sftware specifying an area f statistics, a list f regins, a list f categries (industries r cmmdities) and a perid f time specified by start and end date. The API shuld return the statistics accrding t the area f statistics. Fr this applicatin there are tw main areas: Retail and MerchandiseExprts. If user requests Retail, the API shuld return the mnthly retail turnver f each regin and each categry, fr the specified perid f time. If the user requested MerchandiseExprts as the statistics area, mnthly value f each cmmdity listed in the categries, fr each regin and fr defined time perid, shuld be returned. Page 2

3 Figure 1 shws hw a system wuld interact with the Australian Statistics API. Statistics area, list f regins, a list f categries, perid f time Australian Statistics API System List f values fr each categry and regin fr given perid f time, accrding t the area f statistics Figure 1 - High level view The prgramming language in which the mdule is t be written is nt imprtant as lng as there is sme way t invke it frm ur system. The utput f the Australian Statistics API shuld be a JSON file cntaining data in the frmat specified belw. It is imprtant that the mdule can be used withut its surce cde being revealed. Input Parameters fr API The API we develp shuld be able t take fur inputs as defined by fllwing table. Parameter StatisticsArea State Categry Arguments and Frmats A string which can take value Retail r MerchandiseExprts. A list f ne r mre regins (AUS, NSW, WA, SA, ACT, VIC, TAS, QLD, NT) separated by,. If StatisticsAria is Retail, a list f ne r mre industry (Ttal, Fd, HusehldGd, ClthingFtwareAndPersnalAccessry, DepartmentStres, CafesResturantsAndTakeawayFd, Other) separated by,. OR startdate enddate If StatisticsAria is MerchandiseExprts, a list f ne r mre cmmdities f interest frm (Ttal,FdAndLiveAnimals, BeveragesAndTbacc, CrudMaterialAndInedible, MineralFuelLubricentAndRelatedMaterial, AnimalAndVegitableOilFatAndWaxes, ChemicalsAndRelatedPrducts, ManufacutedGds, MachineryAndTransprtEquipments, OtherManucacturedArticles, Unclassified) separated by,. In the frmat f YYYY-MM-DD In the frmat f YYYY-MM-DD Page 3

4 Output Specificatin fr the API 4.1 Fr Retail Statistics Area The mdule shuld return a jsn file with data requested by user, in the frmat defined in Appendix 6.2. The frmat f utput data types shuld be as fllws: RetailIndustry State Date Turnver Output Parameter Data Frmat String value frm (Ttal, Fd, HushldGd, ClthingFtwareAndPersnalAccessry, DepartmentStres, CafesResturantsAndTakeawayFd, Other) String value frm (AUS, NSW, WA, SA, ACT, VIC, TAS, QLD) Last day f each mnth in YYYY-MM-DD frmat. A flating pint value 4.2 Fr Merchandise Exprt Area The mdule shuld return a jsn file with data requested by user, in the frmat defined in Appendix 6.3. The frmat and data types f utput data types shuld be as fllws: Parameter Cmmdity State Date Value Data Type String value frm (Ttal,FdAndLiveAnimals, BeveragesAndTbacc, CrudMaterialAndInedible, MineralFuelLubricentAndRelatedMaterial, AnimalAndVegitableOilFatAndWaxes, ChemicalsAndRelatedPrducts, ManufacutedGds, MachineryAndTransprtEquipments, OtheranucacturedArticles, Unclassified) String value frm (AUS, NSW, WA, SA, ACT, VIC, TAS, QLD, NT) Last day f each mnth in YYYY-MM-DD frmat. A flating pint value Anther utput f the API is a lg file must cntain the fllwing infrmatin: Develper team Mdule name and versin Parameters passed An indicatin if executin has been successful r there is an errr If errr, indicate the nature f the errr If successful, need t supply Ø Start date and time f executin Ø End date and time f executin Ø Elapsed time Page 4

5 Ø Output file name Acquiring the data fr the API T fulfil the user request abut retail trades, yu will need t have a data surce. Fr this, yu shuld use the REST API prvided by Australian Bureau f Statistics (ABS) ( 5.1 Retail Data Amng the varius data sets they prvide, the API needs the Mnthly Retail Turnver by Industry Grup. ABS prvide different mechanisms f filtering and acquiring the data as excel files, csv files r ver a REST API URL. Yu shuld use the REST API URL in the applicatin, t filter and acquire data dynamically, t match with the parameters prvided. T understand the API and data sets yu can visit page ( and navigate t INDUSRTY-> Retail and Whlesale Trade -> Retail -> Retail Trade -> Mnthly Retail Turnver by Industry Grup Yu can custmize the data set by changing varius parameters at Selectin tab as shwn in figure abve. Accrding t the parameters yu change, the URL can be generated at Exprt Tab-> Develper API tab -> Generate API Query buttn URL: Exprt -> Develper API tab -> Generate API Query buttn Fr ur API, we are interested in the Regin, Retail Industry Type and Time and Frequency Parameters. Other parameters can be left as fllws: Data Type: Current Prices ($Millin) Adjustment Type: Original Fr further clarificatins, given belw is a sample URL: Page 5

6 The highlighted part f the URL can be used t pass parameters t the ABS API. If we cnsider the part M, each categry f parameter is separated by. In the rder f indexes f the Regin, Index f data type, ID fr retail industry, ID f adjustment type and Time & Frequence indicatr. + sign is used t separate a list f attributes passed t ne parameter. Fllwing table explains the parameters passed in the example URL. Explre the parameters further by explring the web page. Parameter Referred Meaning Request data fr three regins (0: Australia, 1: New Suth Wales, 2: Victria). Yu can use frm 0 t 8 numbers. 2 Refer t the data type (2-Current Prices ($Millin)). Yu can keep this as default Refer t a list f IDs fr retail industry (20- Ttal, 41- Fd Retailing, 42-Husehld Gd Retailing). Explre further in web page. 10 Refer t the Adjustment type (10-Original). Yu can keep this as default. M Request Mnthly data starttime= &endtime= Used t define the duratin, fr which data is requested. The ABS API will return dataset as JSON file, each data value indexed accrding t the parameters. The indexing is described at the end f the JSON file. Yu can type the abve given URL n the brwser and bserve the utput frmat. The data structure can be fund in fllwing link : Merchandise Exprt Data Fr Merchandise Exprt, the API needs the Mnthly Value f Exprts by Cmmdity. ABS prvide different mechanisms f filtering and acquiring the data as excel files, csv files r ver a REST API URL. Yu shuld use the REST API URL in the applicatin, t filter and acquire data dynamically, t match with the parameters prvided. T understand the API and data sets yu can visit page ( and navigate t ECONOMY -> Internatinal Trade -> Exprts -> Merchandise Exprts -> Key Figures, Exprts by SITC Page 6

7 Yu can custmize the data set by changing varius parameters at Selectin tab as shwn in figure abve. Accrding t the parameters yu change, the URL can be generated at Exprt Tab-> Develper API tab -> Generate API Query buttn Fr ur API, we are interested in the State Of Origin, Cmmdity by SITC and Time and Frequency Parameters. Other parameters can be left as fllws: Industry f rigin - Ttal Cuntry f destinatin Ttal Fr further clarificatins, given belw is a sample URL: The highlighted part f the URL can be used t pass parameters t the ABS API. If we cnsider the part F M, each categry f parameter is separated by. In the rder f IDs fr list f State f Origin, List f Cmmdity by SITC, List f Industry f Origin, List f Cuntry f Destinatin and Time & Frequency indicatr. + sign is used t separate a list f attributes passed t ne parameter. Fllwing table explains the parameters passed in the example URL. Explre the parameters further by explring the web page. Parameter Referred Meaning Request data fr State f Origin (- : ttal, 1 : New Suth Wales) Find IDs fr ther states using the ABS web site Refer t the cmmdity by SITC (-1:Ttal, 0 - Fd and Live Animals ) Find IDs fr ther cmmdities using the ABS web site. Page 7

8 -1 Refer t the industry f rigin. Keep 1 as default t cnsider all the industries. - Refer t the cuntry f destinatin. Keep as default t indicate ttal f exprts. M Request Mnthly data starttime= &endtime= Used t define the duratin, fr which data is requested. The ABS API will return dataset as JSON file, each data value indexed accrding t the parameters. The indexing is described at the end f the JSON file. Example file type the given URL in the brwser and bserve the results returned. Appendix 6.1 Additinal Infrmatin: Teams have the chice f running their system n tw different platfrms: Standalne Prgram PC running Windws Unix/Linux platfrm Web service (accessible via a REST interface) Thrughut the wrkshp, each team will need t have a Web page. As a minimum, the page is shwing: The team name and members Cnsecutive releases f their mdule. Each release page must include a link t dwnlad the mdule and infrmatin abut: The date and versin f the release What has been implemented s far Differences with previus versin Clear instructins n hw t run the mdule in standalne mde Guidelines n hw t integrate the mdule with ther systems Any test sftware r data Page 8

9 { 6.2 Sample Output Frmat fr Retail "MnthlyRetailData": [ { RetailIndustry :<>, ReginalData :[ { Mnth :<>, { Mnth :<>, ] } { RetailIndustry :<>, ReginalData :[ ] } Page 9

10 { 6.3 Sample Output Frmat fr Merchandise Exprt "MnthlyCmmdityExprtData": [ { Cmmdity :<>, ReginalData :[ ] } { Cmmdity :<>, State :[ {Regin:<>, ] } Page 10

11 6.4 References: [1] ABS.Stat : Page 11