Listing Schema

Each listing is represented by a JSON object containing detailed business information, including addresses, phone numbers, services and much more.

The amount of information provided differs between listings (ie, not all listings will have all fields populated). See the Optional column in the documentation below to know which fields are always going to be returned, and which fields may not be.

This section applies to the endpoints:

Note: Any undocumented properties are subject to change without notice and are used at your own risk.

Example

A fully-populated listing object in JSON will have the following structure:

{
    "id": "...",
    "name": "...",
    "shortDescriptor": "...",
    "mediumDescriptor": "...",
    "serviceNotes": "...",
    "detailsLink": "...",
    "pureMobileBusiness": "...",
    "priceQualifier": "...",
    "hasExposureProducts": "...",
    "businessLogo": {
        "url": "...",
        "altText": "..."
    },
    "businessInfo": {
        "legalId": "...",
        "abn": "...",
        "acn": "...",
        "numberOfEmployees": "...",
        "dateEstablished": "..."
    },
    "categories": [
        {
            "id": "...",
            "name": "...",
            "sensitive": "..."
        },
        ...
    ]
    "primaryContacts": [
        {
            "value": "...",
            "description": "...",
            "type": "..."
        },
        ...
    ],
    "secondaryContacts": { 
        "(groupName)": [
            {
                "type": "...",
                "value": "...",
                "description": "...",
            },
            ...
        ],
    ...
    },
    "orderedSecondaryContacts": [
        {
            "name": "(groupName)",
            "contacts": [ 
               {
                 "type": "...",
                 "value": "...",
                 "description": "..."
               },
               ...
             ]
        },
        ...
    ],
    "primaryAddress": {
        "addressLine": "...",
        "type": "...",
        "suburb": "...",
        "state": "...",
        "postcode": "...", 
        "latitude": "...",
        "longitude": "...",
        "geoCodeGranularity": "...",
	"mappable": "...", 
        "coordinates":{ ... }
    },
    "additionalAddresses": [  
        {
            "addressLine": "...",
            "type": "...",
            "suburb": "...",
            "state": "...",
            "postcode": "..."
        }
    ],
    "productKeywords": {
        "...": [
            "..."
        ]
    },
    "orderedProductKeywords": [
        {
            "label": "...",
            "values": [
                "..."
            ]
        }
    ],
    "imageGallery": [
        {
            "thumbnailUrl": "...",
            "largeUrl": "...",
            "altText": "..."
        }
    ],
    "externalLinks": [
        {
            "type": "...",
            "url": "...",
            "displayValue": "...",
            "label": "...",
            "description": "...",
            "logo": "..."
        }
    ],
    "tradingAliases": [
        "..."
    ],
    "reportingId": "...",
    "openingHours": {
        "...": {
            "status": "...",
            "times": [
                {
                    "open": "...",
                    "close": "..."
                },
                ...
            ]
        },
        ...
    },
    "distance": 5.622840714192739,
    "reviewSummaries": [
       {
          "namespace": "...",
          "reviewCount": "...",
          "businessPageUrl": "...",
          "averageRating": "...",
          "ratingImageUrl": "...",
          "ratingSmallImageUrl": "..."
       }
    ],
    "reviews": [
       {
          "namespace": "http://www.yelp.com.au",
          "text": "...",
          "reviewUrl": "...",
          "reviewTimestamp": "...",
          "reviewerName": "...",
          "reviewerAvatarUrl": "...",
          "rating": "...",
          "ratingImageUrl": "...",
          "ratingSmallImageUrl": "..."
      },
    ],
    "pois": {
        "results": [
          { … },
          { … },
          { … },
          { … },
          { … },
          { … },
          { … },
          { … },
          { … },
          { … }
        ],
        "totalResults": "..."
    }
}

Properties

PropertyTypeDescriptionOptional
id String Unique identifier for this listing. This value can be used to bookmark the listing and later retrieval using the Get by Listing ID endpoint. No
name String Name of the business. No
shortDescriptor String Short business description (70 characters maximum). Usually the first description displayed. Yes
mediumDescriptor String Secondary business description (160 characters maximum). Usually the second description displayed. Yes
serviceNotes String Additional details about opening hours or service (eg, 'By Appointment Only'). Yes
detailsLink String URL of listing on the Yellow Pages website. This page displays all details of the business including a map showing the location. No
pureMobileBusiness Boolean If the business is a mobile business (such as a mobile dog wash). Yes
pmbServicingMessage String Additional details about a Purely Mobile Business. Usually advising a service is provided in the area.
priceQualifier String Information about rates and prices (eg, call costs for a phone service). Yes
hasExposureProducts Boolean If this business has exposure advertising products that ensures this business appears for searches in this location. Yes
businessLogo String The url and altText of the business logo. See businessLogo. Yes
businessInfo String Details of the business itself, such as the number of employees and the date established. See businessInfo. Yes
categories Array List of categores that the business is listed uner. See categories. Yes
primaryContacts Array List of primary contact details. See primaryContacts. No
secondaryContacts Object Deprecated. List of secondary contact details. See secondaryContacts. Yes
orderedSecondaryContacts Array List of secondary contact details. See orderedSecondaryContacts. Yes
primaryAddress Object The primary business address. See primaryAddress. No
additionalAddresses Array List of additional business addresses. Each array item follows the same structure as primaryAddress. No
productKeywords Object Deprecated. Keywords associated with the business. See productKeywords. Yes
orderedProductKeywords Array Keywords associated with the business. See orderedProductKeywords. Yes
imageGallery Array Gallery of images associated with the listing. See imageGallery. Yes
externalLinks Array Additional links related to the listing (eg, a link to Trading Post advertisments). See externalLinks. Yes
tradingAliases Array List of aliases that the business trades under. Yes
reportingId String Reporting id information required for reporting usage events for current listing. See Reporting Usage Events. Yes
openingHours Object The opening hours of the business. See openingHours. Yes
distance Double The distance in kilometres between the centrepoint of the searched location and the listing. This is returned if you specify sortBy=DISTANCE. Yes
reviewSummaries Array List of review summaries for all the different namespaces that the business has. Each review summary is for a given namespace. See Review Summaries Yes
reviews Array List of individual reviews that the business has. See Reviews Yes
pois Array List of points of interest surrounding a business. See pois Yes

businessLogo

The businessLogo field contains details relating to the logo of a business.

"businessLogo": [ 
    {
        "url": "...",
        "altText": "...",
    }
]

Each object can have the following properties:

Property Type Description
url String The url of the logo image.
value String Alternate text for the business logo. Can be used, for example, as the alternate text for HTML images tags.

businessInfo

The businessInfo field contains details relating to the operation of a business.

"businessInfo:{
    "legalId": "...",
    "abn": "...",
    "acn": "...",
    "numberOfEmployees": "...",
    "dateEstablished": "..."
}

Each object can have the following properties:

Property Type Description Optional
legalId String Legal identifier associated with the business (eg, liquor licence number). Yes
abn String Australian Business Number Yes
acn String Australian Company Number Yes
numberOfEmployees String Approximate number of employees (eg, '25-50'). Yes
dateEstablished String Date the business was established. Yes

categories

The categories field shows how a listing has been categorised. Item list item represents one category that the business has been listed under.

"categories": [
    {
        "id": "...",
        "name": "...",
        "sensitive": "..."
    }
]

This field contains an array of each objects, where each object has the following properties:

Property Type Description Optional
id String Unique ID associated with the category. No
name String The name of the category the business is listed under. No
sensitive Boolean If true, indicates that the category may contain sensitive content, such as adult business listings. Yes

primaryContacts

The primaryContacts field contains a list of the primary contacts for the business.

"primaryContacts": [ 
    {
        "type": "...",
        "value": "...",
        "description": "...",
    }
]

Each object in the array can have the following properties:

Property Type Description Optional
type String The type of contact. See the table below for possible values. No
value String The contact detail. Maybe a phone number, web address or email. No
description String Contains a short description of the contact. Yes

Possible values for the type property:

Value Description
URL Website address
MOBILE Mobile phone number
PAGER Pager number
PHONE Phone number
INTERNATIONAL International phone number
FAX FAX number
EMAIL Email address

secondaryContacts

The secondaryContacts field contains a list of additional contacts for the business. These are identical in format as the primaryContacts, the only difference is that they are presented in logical groupings.

"secondaryContacts": {
    "(groupName)": [
        {
                "type": "...",
                "value": "...",
                "description": "...",
        }
    ]
}

We encourage you to use the new orderedSecondaryContacts in place of this field.

orderedSecondaryContacts

The orderedSecondaryContacts field contains a list of additional contacts for the business. They are presented in logical groupings.

"orderedSecondaryContacts": [
    {
       "name": "(groupName)",
       "contacts": [ 
          {
             "type": "...",
             "value": "...",
             "description": "..."
          },
          ...
        ]
     },
     ...
]

primaryAddress

The primaryAddress property contains details of the business's main address.

"primaryAddress": {
    "type": "...",
    "addressLine": "...",
    "suburb": "...",
    "state": "...",
    "postcode": "...", 
    "latitude": "...",
    "longitude": "...",
    "geoCodeGranularity": "...", 
    "mappable": "...", 
    "coordinates": {
       "centre":{
          "longitude": ...,
          "latitude": ...
       },
       "street": {
          "longitude": ...,
          "latitude": ...
       }
    }
}

Object properties:

Property Type Description Optional
type String The type of address. See table below for possible values. No
addressLine String Address line (eg, level/unit number, street number and street name). Yes
suburb String Suburb or town name. No
postcode String Postcode No
latitude String Latitude of business address (may be approximate). Can be used for plotting business location on a map. This is only provided for primaryAddress if applicable. (Must be paired with Longitude) Yes
longitude String Longitude of business address (may be approximate). Can be used for plotting business location on a map. This is only provided for primaryAddress if applicable. (Must be paired with Latitude) Yes
geoCodeGranularity String Describes the precision of latitude and longitude. See table below for possible values. No
mappable Boolean Mappable is a boolean indicator on whether a listing can be mapped to a specific location. Essentially if geoCodeGranularity is equal to either a "PROPERTY", or "INTERSECTION". it can be mapped. No
centre.latitude number Centrepoint latitude of business address (may be approximate). Can be used for plotting business location on a map. This is only provided for primaryAddress if applicable. Yes
centre.longitude number Centrepoint longitude of business address (may be approximate). Can be used for plotting business location on a map. This is only provided for primaryAddress if applicable. Yes
street.latitude number Streetpoint latitude of business address (may be approximate). May be used for routing purposes. Typically, streetPoint is on a navigable street and identifies a location different from centrePoint. This is only provided for primaryAddress if applicable. Yes
street.longitude number Streetpoint longitude of business address (may be approximate). May be used for routing purposes. Typically, streetPoint is on a navigable street and identifies a location different from centrePoint. This is only provided for primaryAddress if applicable. Yes

Possible values for the type property:

Value Description
VANITY Vanity address. A vanity address usually contains a familiar point of interest rather than an exact street address. For example, a business located in a shopping centre may use the name of the shopping centre rather than the actual street address of the centre.
PHYSICAL Physical business address. This is the physical location of the business's store, office or other building.
POSTAL Postal address. Often different from physical address, especially if the business has a Post Office (PO) box.

Possible values for the geoCodeGranularity property:

Value Description
PROPERTY The location is resolved to a property granularity where the latitude and longitude are the centroid of the property.
STREET The location is resolved to a street granularity where the latitude and longitude are the centroid of the street.
INTERSECTION The location is resolved to a street intersection where the latitude and longitude are the centroid of the street intersection.
SUBURB The location is resolved to a suburb granularity where the latitude and longitude are the centroid of the suburb.
REGION The location is resolved to a region granularity where the latitude and longitude are the centroid of the region.
STATE The location is resolved to a state granularity where the latitude and longitude are the centroid of the state.

productKeywords

This is deprecated but will continue to be supported; please use orderedProductKeywords.

The productKeywords property contains a number of words and phrases associated with the listing.

"productKeywords": {
    "(field)": [
        "(value)",
        ...
    ]
}

Product keywords are keywords related to a business such as 'Cash', to indicate a payment method, or '24-hour', to indicate opening hours. Product keywords are categorised in to fields (eg, 'Payment Method' and 'Opening Hours'). Note that the field names and values are free-text and don't adhere to any particular rules, and may change over time.

Each field is represented by a property, where the name of the property is the field name and the children are the keyword values.

We encourage you to use the new orderedProductKeywords in place of this field.

orderedProductKeywords

The orderedProductKeywords property contains a list of words and phrases associated with the listing.

"orderedProductKeywords": [
    {
        "label": "(field)",
        "values": [
            "(value)",
            ...
        ]
    },
    ...
]

Product keywords are keywords related to a business such as 'Cash', to indicate a payment method, or '24-hour', to indicate opening hours. Product keywords are categorised in to fields (eg, 'Payment Method' and 'Opening Hours'). Note that the field names and values are free-text and don't adhere to any particular rules, and may change over time.

Each list item contains the following properties:

Property Type Description Optional
label String The field name. No
values Array The field values as an array of String. No

The fields and values are the same as the those available on the Yellow Pages website when you refine a search (see the 'Refine By:' field on the Yellow Pages search page).

imageGallery

The imageGallery property can contain links to a number of images provided by the advertiser.

"imageGallery": [
    {
        "thumbnailUrl": "...",
        "largeUrl": "...",
        "altText": "..."
    }
]

Each gallery item is a JSON object with the following properties:

Property Type Description Optional
thumbnailUrl String Location of a thumbnail (small) version of the image. No
largeUrl String Location of the full-sized version of the image. No
altText String Text that can be used, for example, as the alternate text for an HTML image. Yes

externalLinks

The externalLinks property can contain additional links related to the listing. For example, may contain links to Trading Post advertisements.

"externalLinks": [
    {
        "type": "...",
        "url": "...",
        "displayValue": "...",
        "label": "...",
        "description": "...",
        "logo": "..."
    }
]

Each item is a JSON object with the following properties:

Property Type Description Optional
type String Type of link. Currently always DEEP_LINK. No
url String The actual link location. No
displayValue String Display value for the link. Usually used, for example, as the anchor text of an HTML link. No
label String Link label that can be used for grouping links under a common heading. Yes
description String Additional description of the link. Yes
logo String Location of a logo image related to the link. Yes

openingHours

The openingHours property contains the hours the business is open each day.

"openingHours": {
    "...": {
        "status": "...",
        "times": [
            {
                "open": "...",
                "close": "..."
            },
            ...
        ]
    },
    ...
}

This field is a JSON object with properties representing the days:

  • monday
  • tuesday
  • wednesday
  • thrusday
  • friday
  • saturday
  • sunday
  • publicHolidays

If any day is omitted, the opening ours for that day are unknown (it does not that imply the business is closed).

Each day is again an object, containing a status and (optionally) a list of periods during which the business is open. For example, a business may be open in the morning, closed for lunch and open in the afternoon. In this case, there would be two items in the times property.

Note: Currently, the times property will contain at most two periods. However this may change in the future.

Property Type Description Optional
status String Indicates whether the business is open or closed. See table below for all possible values. No
times Array Zero or more periods during which the business is open. See table below for the structure of each item. Yes

The following table lists the values for the status property.

Status Description
open The business is open. There will be at least one period in the times property to indicate the exact hours they are open for.
closed The business is closed all day. There will be no times property.
byAppointment The business is only open for pre-arranged appointments. There will be no times property.
24hours The business is open all day. There will be no times property.

The following table shows the structure of each times item.

Property Type Description Optional
open Time When the business opens. Format is hh:mm, in 24-hour time. No
close Time When the business closes. Format is hh:mm, in 24-hour time. No

Review Summaries

The reviewSummaries property contains summary information about the reviews that others have posted about this business.

 "reviewSummaries": [
     {
       "namespace": "http://www.yelp.com.au",
       "reviewCount": 5,
       "businessPageUrl": "http://www.yelp.com.au/biz/draculas-carlton-2",
       "averageRating": 3.5,
       "ratingImageUrl": "http://s3-media3.ak.yelpcdn.com/assets/2/www/img/5ef3eb3cb162/ico/stars/stars_3_half.png",
       "ratingSmallImageUrl": "http://s3-media3.ak.yelpcdn.com/assets/2/www/img/2e909d5d3536/ico/stars/stars_small_3_half.png"
     }
 ]

Each item is a JSON object with the following properties:

Property Type Description Optional
namespace String Where the reviews have been posted or the source of the review content e.g http://www.yelp.com.au No
reviewCount Integer The total number of reviews from this namespace. However, some reviews will be removed if they contain profanities. In this case the count will not be altered which means that the number of reviews you see may not match the reviewCount. No
businessPageUrl String This link will take you to the content of the reviews e.g http://www.yelp.com.au/biz/draculas-carlton-2 Yes
averageRating Double The average rating of all the reviews from this given namespace. Example 3.5 Yes
ratingImageUrl String This is a link to an image that represents the average rating number above. Yes
ratingSmallImageUrl String This is a link to a smaller vesrion of the image that represents the average rating number above. Yes

Reviews

The reviews property contains an array of JSON objects representing the review.

 "reviews": [
    {
        "namespace": "http://www.yelp.com.au",
        "text": "Well, my night at Dracula's wasn't half as painful as I thought it would be! ...",
        "reviewUrl": "http://www.yelp.com.au/biz/draculas-carlton-2#hrid:gGpUJN1cCItli6Dx0tl6Rg",
        "reviewTimestamp": "2011-11-08T20:00:37.000+1100",
        "reviewerName": "John S",
        "reviewerAvatarUrl": "http://s3-media1.ak.yelpcdn.com/photo/not_existence/link.jpg",
        "rating": 4,
        "ratingImageUrl": "http://www.yellowpages.com.au/ui/standard/yelp_4stars.png",
        "ratingSmallImageUrl": "http://www.yellowpages.com.au/ui/standard/yelp_4stars_small.png"
    }
 ]

Each review can have the following properties:

Property Type Description Optional
namespace String Where the reviews have been posted or the source of the review content e.g http://www.yelp.com.au No
text String The full review or snippet(truncated review) of the review depending on the which namespace the review is coming from. No
reviewTimestamp Date The timestamp when the review was created Yes
reviewerName String The name of the reviewer Yes
reviewerAvatarUrl String The URL to avatar of the reviewer Yes
rating Integer The rating for the review e.g 4. Yes
ratingImageUrl String The link to an image representing the rating when the actual rating number is not available. Yes
ratingSmallImageUrl String The link to a smaller image representing the rating when the actual rating number is not available. Yes

pois

The pois property contains points of interest (POI), such as railway stations, car parks, ATMs, which are located within 5km of the business. pois are available on the getByListingId endpoint when includePois=true is provided

"pois": {
    "results": [
      { … },
      { … },
      { … },
      { … },
      { … },
      { … },
      { … },
      { … },
      { … },
      { … }
    ],
    "totalResults": "..."
}

Object properties:

Property Type Description Optional
results Array List of up to 10 POI listings (Eg. railway stations, car parks, ATMs) surrounding the business, sorted by distance. POI listings have the same format as business listings. Yes
totalResults number Total number of POI listings (Eg. railway stations, car parks, ATMs) surrounding the business Yes