Search Facets
Quick start – using facets
Retrieve the valid facet values
Add the query parameter showFacets=true to the URL https://data.csiro.au/dap/ws/v2/collections along with your other query parameters (e.g. https://data.csiro.au/dap/ws/v2/collections?q=water&showFacets=true).
Each facet item returned has two elements:
- field
- values
The values element contains a list items that contain the fields:
- value
- count
Use a search facet:
- Take the value of the facet item’s field key (e.g. Collection Types).
- Take one of the items from the facet items values (e.g. the first one).
- Take the value of the item’s value key (e.g. Data).
- Use the field and the value to construct a key-value URL query parameter (e.g. Collection%20Types=Data).
- Add this URL query parameter to the original URL.
- Repeat this for other facets. You may repeat an individual facet to filter on more than one value (e.g. https://data.csiro.au/dap/ws/v2/collections?q=water&showFacets=True&Collection%20Types=Data&Categories=Environmental%20Monitoring&Categories=Climate%20Change%20Processes).
More Information
Search facets allow you to filter search results obtained from https://data.csiro.au/dap/ws/v2/collections. These facets can be used in conjunction with query parameters to limit the number of results retrieved.
Whereas a query parameter will be searched across all accessible collections, search facets are only applied to the results of the search.
Additionally, using multiple search facets of the same type will increase the number of results that you receive. Using multiple query parameters will limit the results, e.g.
| Query Parameter Search | Facet Search |
|---|---|
| Query Parameters Search Terms: q=water&q=soil Results: All accessible records containing both water and soil | Facet Search Terms: q=water?Categories=Environmental Monitoring&Categories=Climate Change Processes Results: All accessible records containing water; then filtered for records in the categories of either Environmental Monitoring or Climate Change Processes. A record need not have both categories to be included. |
Search facets in the DAP web service function the same way as the Refine Results feature found in the DAP user interface search results:
Description of available facets
If the showFacets query parameter is not provided it will default to false.
The available facets will be contained in a “facets” element. A list of the most frequently occurring values and the count of the results for that value are included for each available facet.
https://data.csiro.au/dap/ws/v2/collections?q=water&showFacets=True
JSON Response (click to expand)
JSON Response
Open allClose all{
“query”: “water”,
“elapsedTime”: 17,
“totalResults”: 206,
“page”: 1,
“resultsPerPage”: 25,
“showOnlyUnrestrictedData”: false,
“sortBy”: “RELEVANCE”,
“complete”: false,
“next”: {
“relationship”: “next”,
“mediaType”: null,
“href”: “https://data.csiro.au/dap/ws/v2/collections.json?q=water&showFacets=True&p=2”
},
“first”: {
“relationship”: “first”,
“mediaType”: null,
“href”: “https://data.csiro.au/dap/ws/v2/collections.json?q=water&showFacets=True&p=1”
},
“last”: {
“relationship”: “last”,
“mediaType”: null,
“href”: “https://data.csiro.au/dap/ws/v2/collections.json?q=water&showFacets=True&p=9”
},
“facets”: [
{
“field”: “filesCanAccessCount”,
“values”: [
{
“value”: “filesCanAccessCount”,
“count”: 157
}
]
},
{
“field”: “aggDateRanges”,
“values”: [
{
“value”: “within last year”,
“count”: 38
},
{
“value”: “within last month”,
“count”: 0
},
{
“value”: “within last week”,
“count”: 0
},
{
“value”: “within last day”,
“count”: 0
}
]
},
{
“field”: “Collection Types”,
“values”: [
{
“value”: “Data”,
“count”: 198
},
{
“value”: “Software”,
“count”: 8
}
]
},
{
“field”: “Categories”,
“values”: [
{
“value”: “Environmental Monitoring”,
“count”: 44
},
{
“value”: “Climate Change Processes”,
“count”: 37
},
{
“value”: “Natural Resource Management”,
“count”: 27
},
{
“value”: “Soil Sciences not elsewhere classified”,
“count”: 23
},
{
“value”: “Environmental Management”,
“count”: 19
},
{
“value”: “Landscape Ecology”,
“count”: 17
},
{
“value”: “Physical Oceanography”,
“count”: 17
},
{
“value”: “Biological Oceanography”,
“count”: 15
},
{
“value”: “Land Capability and Soil Degradation”,
“count”: 15
},
{
“value”: “Hydrogeology”,
“count”: 14
}
]
},
{
“field”: “Projects”,
“values”: [
{
“value”: “Legacy data”,
“count”: 23
},
{
“value”: “1181.2 TERN Facility No9 InfoGrid GRUNDY”,
“count”: 20
},
{
“value”: “Marine National Facility”,
“count”: 13
},
{
“value”: “1211.1 Gulf Agricultural Resource Assess”,
“count”: 11
},
{
“value”: “Gascoyne River AEM”,
“count”: 11
},
{
“value”: “1177.2 Northern NERP – Remote Sensing”,
“count”: 10
},
{
“value”: “Future Reef MAP2”,
“count”: 9
},
{
“value”: “1177.1 TERN Supersite – QUT Component”,
“count”: 6
},
{
“value”: “Acquired”,
“count”: 4
},
{
“value”: “1006.12 MARSUO Task 4 Infrastruc & Aesth”,
“count”: 3
}
]
},
{
“field”: “People”,
“values”: [
{
“value”: “CSIRO”,
“count”: 33
},
{
“value”: “Steven, Andy”,
“count”: 17
},
{
“value”: “Austin, Jenet”,
“count”: 15
},
{
“value”: “Clifford, David”,
“count”: 13
},
{
“value”: “Gallant, John”,
“count”: 13
},
{
“value”: “Glover, Mark”,
“count”: 13
},
{
“value”: “Bartley, Rebecca”,
“count”: 12
},
{
“value”: “Gregory, Linda”,
“count”: 12
},
{
“value”: “Anstee, Janet”,
“count”: 11
},
{
“value”: “Botha, Hannelie”,
“count”: 11
}
]
},
{
“field”: “Activity Types”,
“values”: [
{
“value”: “Modelling”,
“count”: 67
},
{
“value”: “Measurement”,
“count”: 44
},
{
“value”: “Observation”,
“count”: 30
},
{
“value”: “Analysis”,
“count”: 18
},
{
“value”: “Experiment”,
“count”: 13
},
{
“value”: “Survey”,
“count”: 8
},
{
“value”: “DesktopStudy”,
“count”: 6
},
{
“value”: “CaseStudy”,
“count”: 4
},
{
“value”: “Calculation”,
“count”: 2
},
{
“value”: “Simulation”,
“count”: 1
}
]
}
],
“dataCollections”: [
…
XML Response
Open allClose all?xml version=”1.0″ encoding=”UTF-8″ standalone=”yes”?>
<dap:dataCollectionsResult xmlns:dap=”urn:au:csiro:rds:dap:1.0″>
<dap:query>water</dap:query>
<dap:elapsedTime>24</dap:elapsedTime>
<dap:totalResults>206</dap:totalResults>
<dap:page>1</dap:page>
<dap:resultsPerPage>25</dap:resultsPerPage>
<dap:first rel=”first” href=”https://data.csiro.au/dap/ws/v2/collections?q=water&showFacets=True&p=1″/>
<dap:next rel=”next” href=”https://data.csiro.au/dap/ws/v2/collections?q=water&showFacets=True&p=2″/>
<dap:last rel=”last” href=”https://data.csiro.au/dap/ws/v2/collections?q=water&showFacets=True&p=9″/>
<dap:showOnlyUnrestrictedData>false</dap:showOnlyUnrestrictedData>
<dap:sortBy>RELEVANCE</dap:sortBy>
<dap:facets>
<dap:facet>
<dap:field>filesCanAccessCount</dap:field>
<dap:values>
<dap:value>
<dap:value>filesCanAccessCount</dap:value>
<dap:count>157</dap:count>
</dap:value>
</dap:values>
</dap:facet>
<dap:facet>
<dap:field>aggDateRanges</dap:field>
<dap:values>
<dap:value>
<dap:value>within last year</dap:value>
<dap:count>38</dap:count>
</dap:value>
<dap:value>
<dap:value>within last month</dap:value>
<dap:count>0</dap:count>
</dap:value>
<dap:value>
<dap:value>within last week</dap:value>
<dap:count>0</dap:count>
</dap:value>
<dap:value>
<dap:value>within last day</dap:value>
<dap:count>0</dap:count>
</dap:value>
</dap:values>
</dap:facet>
<dap:facet>
<dap:field>Collection Types</dap:field>
<dap:values>
<dap:value>
<dap:value>Data</dap:value>
<dap:count>198</dap:count>
</dap:value>
<dap:value>
<dap:value>Software</dap:value>
<dap:count>8</dap:count>
</dap:value>
</dap:values>
</dap:facet>
<dap:facet>
<dap:field>Categories</dap:field>
<dap:values>
<dap:value>
<dap:value>Environmental Monitoring</dap:value>
<dap:count>44</dap:count>
</dap:value>
<dap:value>
<dap:value>Climate Change Processes</dap:value>
<dap:count>37</dap:count>
</dap:value>
<dap:value>
<dap:value>Natural Resource Management</dap:value>
<dap:count>27</dap:count>
</dap:value>
<dap:value>
<dap:value>Soil Sciences not elsewhere classified</dap:value>
<dap:count>23</dap:count>
</dap:value>
<dap:value>
<dap:value>Environmental Management</dap:value>
<dap:count>19</dap:count>
</dap:value>
<dap:value>
<dap:value>Landscape Ecology</dap:value>
<dap:count>17</dap:count>
</dap:value>
<dap:value>
<dap:value>Physical Oceanography</dap:value>
<dap:count>17</dap:count>
</dap:value>
<dap:value>
<dap:value>Biological Oceanography</dap:value>
<dap:count>15</dap:count>
</dap:value>
<dap:value>
<dap:value>Land Capability and Soil Degradation</dap:value>
<dap:count>15</dap:count>
</dap:value>
<dap:value>
<dap:value>Hydrogeology</dap:value>
<dap:count>14</dap:count>
</dap:value>
</dap:values>
</dap:facet>
<dap:facet>
<dap:field>Projects</dap:field>
<dap:values>
<dap:value>
<dap:value>Legacy data</dap:value>
<dap:count>23</dap:count>
</dap:value>
<dap:value>
<dap:value>1181.2 TERN Facility No9 InfoGrid GRUNDY</dap:value>
<dap:count>20</dap:count>
</dap:value>
<dap:value>
<dap:value>Marine National Facility</dap:value>
<dap:count>13</dap:count>
</dap:value>
<dap:value>
<dap:value>1211.1 Gulf Agricultural Resource Assess</dap:value>
<dap:count>11</dap:count>
</dap:value>
<dap:value>
<dap:value>Gascoyne River AEM</dap:value>
<dap:count>11</dap:count>
</dap:value>
<dap:value>
<dap:value>1177.2 Northern NERP – Remote Sensing</dap:value>
<dap:count>10</dap:count>
</dap:value>
<dap:value>
<dap:value>Future Reef MAP2</dap:value>
<dap:count>9</dap:count>
</dap:value>
<dap:value>
<dap:value>1177.1 TERN Supersite – QUT Component</dap:value>
<dap:count>6</dap:count>
</dap:value>
<dap:value>
<dap:value>Acquired</dap:value>
<dap:count>4</dap:count>
</dap:value>
<dap:value>
<dap:value>1006.12 MARSUO Task 4 Infrastruc & Aesth</dap:value>
<dap:count>3</dap:count>
</dap:value>
</dap:values>
</dap:facet>
<dap:facet>
<dap:field>People</dap:field>
<dap:values>
<dap:value>
<dap:value>CSIRO</dap:value>
<dap:count>33</dap:count>
</dap:value>
<dap:value>
<dap:value>Steven, Andy</dap:value>
<dap:count>17</dap:count>
</dap:value>
<dap:value>
<dap:value>Austin, Jenet</dap:value>
<dap:count>15</dap:count>
</dap:value>
<dap:value>
<dap:value>Clifford, David</dap:value>
<dap:count>13</dap:count>
</dap:value>
<dap:value>
<dap:value>Gallant, John</dap:value>
<dap:count>13</dap:count>
</dap:value>
<dap:value>
<dap:value>Glover, Mark</dap:value>
<dap:count>13</dap:count>
</dap:value>
<dap:value>
<dap:value>Bartley, Rebecca</dap:value>
<dap:count>12</dap:count>
</dap:value>
<dap:value>
<dap:value>Gregory, Linda</dap:value>
<dap:count>12</dap:count>
</dap:value>
<dap:value>
<dap:value>Anstee, Janet</dap:value>
<dap:count>11</dap:count>
</dap:value>
<dap:value>
<dap:value>Botha, Hannelie</dap:value>
<dap:count>11</dap:count>
</dap:value>
</dap:values>
</dap:facet>
<dap:facet>
<dap:field>Activity Types</dap:field>
<dap:values>
<dap:value>
<dap:value>Modelling</dap:value>
<dap:count>67</dap:count>
</dap:value>
<dap:value>
<dap:value>Measurement</dap:value>
<dap:count>44</dap:count>
</dap:value>
<dap:value>
<dap:value>Observation</dap:value>
<dap:count>30</dap:count>
</dap:value>
<dap:value>
<dap:value>Analysis</dap:value>
<dap:count>18</dap:count>
</dap:value>
<dap:value>
<dap:value>Experiment</dap:value>
<dap:count>13</dap:count>
</dap:value>
<dap:value>
<dap:value>Survey</dap:value>
<dap:count>8</dap:count>
</dap:value>
<dap:value>
<dap:value>DesktopStudy</dap:value>
<dap:count>6</dap:count>
</dap:value>
<dap:value>
<dap:value>CaseStudy</dap:value>
<dap:count>4</dap:count>
</dap:value>
<dap:value>
<dap:value>Calculation</dap:value>
<dap:count>2</dap:count>
</dap:value>
<dap:value>
<dap:value>Simulation</dap:value>
<dap:count>1</dap:count>
</dap:value>
</dap:values>
</dap:facet>
</dap:facets>
<dap:dataCollections>
…
Here we see the available items in the facets element:
| Facet | Description |
|---|---|
| filesCanAccessCount | Unlike other facets, this is just giving you a numerical value of how many collections exist where the requester can access the files. This value can be used to determine how many collections would be returned if the the query parameter soud=true (“soud” means Show Only Unrestricted Data) were used. |
| aggDateRanges | These are pre-defined publication date ranges that can be used to search for recently published collections. within last year within last month within last week within last day |
| Collection Types | Different DAP collections can contain different content, which here are described as “collection types”. Data Software Service |
| Categories | Text values of the Australia and New Zealand Standard Research Classification (ANZSRC), 2020 Fields of Research (FoR) codes (i.e. the text description of the Field of Research, not the FoR code itself). All DAP collections have at least one FoR code recorded. The top 10 codes for the used query parameters will be listed. The Australian National Data Service hosts a linked data version of this vocabulary on Research Vocabularies Australia. |
| Projects | The top 10 (by collection count) CSIRO projects that have collections in the result set. |
| People | The top 10 (by collection count) researchers who are attributed in the result set. |
| Activity Types | The top 10 (by collection count) activity types used in the result set. Each DAP collection may have one activity type, although it is not a mandatory field. Possible activity types are: Analysis Calculation Case Study Desktop Study Experiment Forecast Measurement Modelling Observation Pilot Study Questionnaire Simulation Survey Validation |