Category Filtering

The Search endpoint (See Search for details) will return listings which may have been categorised into to zero or more categories. These are displayed in the categories field in each listing returned from a search response (See Listing Schema for details).

Note: A proportion of listings in our index do not have an associated category, and as such will be excluded when using this filter.


You can find category ids with our Category Explorer.

Example

For example, given a request for tyres returned the following listings:

{
    "results": [
        ...
        {
            "name": "Bill's Tyres",
            "categories": [
                {
                    "name": "Tyres--Retail",
                    "id": "24058"
                }
            ]
        },
        {
            "name": "Western Car Tyres",
            "categories": [
                {
                    "name": "Tyres--Retail",
                    "id": "24058" 
                },
                {
                    "name": "Tyres--W'sale",
                    "id": "27855"
                }
            ]
        },
        {
            "name": "Jim's Wholesale Tyres",
            "categories": [
                {
                    "name": "Tyres--W'sale",
                    "id": "27855"
                }
            ]
        },
        {
            "name": "Eastern Tyre Repairs",
            "categories": [
                {
                    "name": "Tyres--Retreading, Recapping & Repairing",
                    "id": "26085"
                }
            ]
        }
        ...
    ],
    ...
}

To filter the search by one or more categories, specify the categoryId parameter. The categoryId value must correspond to the id for the category or category group to be returned.

For example, to filter the tyres search by a single category Tyres--Retail, simply add the categoryId with the Tyres--Retail id of 24058.

http://api.sensis.com.au/v1/test/search?query=tyres&categoryId=24058&key=...

This request should return a response which contains the following listings:

{
    "results": [
        ...
        {
            "name": "Bill's Tyres",
            "categories": [
                {
                    "name": "Tyres--Retail",
                    "id": "24058"
                }
            ]
        },
        {
            "name": "Western Car Tyres",
            "categories": [
                {
                    "name": "Tyres--Retail",
                    "id": "24058" 
                },
                {
                    "name": "Tyres--W'sale",
                    "id": "27855"
                }
            ]
        }
        ...
    ],
    ...
}

To filter the tyres search by a multiple categories, add a categoryId parameter for each category. For example, the Tyres--Retail and Tyres--W'sale categories could be filtered by the following request:

http://api.sensis.com.au/v1/test/search?query=tyres&categoryId=24058&categoryId=27855&key=...

This request should return a response which contains the following listings:

{
    "results": [
        ...
        {
            "name": "Bill's Tyres",
            "categories": [
                {
                    "name": "Tyres--Retail",
                    "id": "24058"
                }
            ]
        {,
        }
            "name": "Western Car Tyres",
            "categories": [
                {
                    "name": "Tyres--Retail",
                    "id": "24058" 
                },
                {
                    "name": "Tyres--W'sale",
                    "id": "27855"
                }
            ]
        {,
        }
            "name": "Jim's Wholesale Tyres",
            "categories": [
                {
                    "name": "Tyres--W'sale",
                    "id": "27855"
                }
            ]
        }
        ...
    ],
    ...
}

 

Points of Interest (POI) Category Filtering

When retrieving a business listing on a getByListingId request it is possible to include surrounding POIs (Eg. railway stations, car parks, ATMs). To filter the included POIs by one or more categories, specify the categoryId parameter one or more times. The categoryId value must correspond to the id for the category to be returned

Example of how to display POIs around a business

FIGURE A: Points of Interest displayed around a Business Listing

Example

For example, given a getByListingId request for 123456 returned the following listing:

{
  "results" : [
     ...
     {
        "name": "Bill's Tyres",
        "id": "123456",
        "categories": [
           {
              "name": "Tyres--Retail",
              "id": "24058"
           }
        ],
        ...
        "pois" :
           {
              "results" : [
                 {
                    "name" : "Information Board Melbourne",
                    "id" : "LN11111111",
                    "categories" : [
                       {
                          "id" : "1002505",
                          "name" : "Information Centres"
                       }
                    ],
                    "primaryAddress" : { ... }
                 },
                 {
                    "name" : "Car Park - Melbourne Carpark",
                    "id" : "LN22222222",
                    "categories" : [
                       {
                          "id" : "1002502",
                          "name" : "Car Parks"
                       }
                    ],
                    "primaryAddress" : { ... }
                 },
                 {
                    "name" : "Public Payphone",
                    "id" : "LN33333333",
                    "categories" : [
                       {
                          "id" : "1002507",
                          "name" : "Public Phone"
                       }
                    ],
                    "primaryAddress" : { ... }
                 },
                 {
                    "name" : "Car Park - East Melbourne Carpark",
                    "id" : "LN44444444",
                    "categories" : [
                       {
                          "id" : "1002502",
                          "name" : "Car Parks"
                       }
                    ],
                    "primaryAddress" : { ... }
                 }
                 ...
              ],
              "totalResults" : 2823
           },
        ...
     },
}

For example, to filter the 123456 request by a single category Car Parks, simply add the categoryId with the Car Parks id of 1002502.

http://api.sensis.com.au/v1/test/getByListingId?query=123456&includePois=true&categoryId=1002502&key=...

This request should return a response which contains the following included POIs:

{
  "results" : [
     ...
     {
        "name": "Bill's Tyres",
        "id": "123456",
        "categories": [
           {
              "name": "Tyres--Retail",
              "id": "24058"
           }
        ],
        ...
        "pois" :
           {
              "results" : [
                 {
                    "name" : "Car Park - Melbourne Carpark",
                    "id" : "LN22222222",
                    "categories" : [
                       {
                          "id" : "1002502",
                          "name" : "Car Parks"
                       }
                    ],
                    "primaryAddress" : { ... }
                 },
                 {
                    "name" : "Car Park - East Melbourne Carpark",
                    "id" : "LN44444444",
                    "categories" : [
                       {
                          "id" : "1002502",
                          "name" : "Car Parks"
                       }
                    ],
                    "primaryAddress" : { ... }
                 }
                 ...
              ],
              "totalResults" : 100
           },
        ...
     },
}