-
Notifications
You must be signed in to change notification settings - Fork 2
Details
Oleg Berman edited this page Feb 2, 2016
·
8 revisions
The DETAILS API allows you to retrieve listing details from n49.ca using a known existing business ID. The business details endpoint will also provide aggregate review rating values which can be restricted to specific properties or omitted to get an aggregate value for all properties.
There are two versions of this endpoint, one is a get request for returning the details for one business. The Details endpoint also supports a post request with an array of business ID's.
Properties
| Property | Value |
|---|---|
| Method | GET |
| URL | data-api.n49.ca/businesses/details |
URL Parameters
| Name | Required? | Description | Example |
|---|---|---|---|
| api_key | Yes | API Key provided by n49.ca | |
| bID | Yes | Business ID returned by n49 in search results. | 888303 |
| property | No | Restricts the aggreagte review rating details to the property specified. | n49 |
Properties
| Property | Value |
|---|---|
| Method | POST |
| URL | data-api.n49.ca/businesses/details |
URL Parameters
| Name | Required? | Description | Example |
|---|---|---|---|
| api_key | Yes | API Key provided by n49.ca | |
| property | No | Restricts the aggregate review rating details to the property specified. | n49 |
BODY Parameters
| TYPE | Required? | Description | Example |
|---|---|---|---|
| JSON object | Yes | a list of the business ID's that you wish to get the details for. It must be formatted as in the example here. | {"companyIds":[925304,928277,738211,22607,923144]} |
Status Codes
| Status Code | Condition | Example Cause |
|---|---|---|
| 200 | OK | The response contains the listing details. |
| 400 | BAD REQUEST | Malformed request. |
| 404 | NOT FOUND | The specified listing does not exist on our site. |
| 5xx | SERVER ERROR | Temporary error -- try again later. Server outage, etc. |
Body
The DETAILS response is a JSON document containing detailed information for the requested listing.
Fields with no value: Unless otherwise noted, please we'll return null for fields that do not have a value, instead of leaving them blank or omitting them from the response.
| Field | Description |
|---|---|
| id | The bID for the listing |
| status | Status of the listing. AVAILABLE: This listing is available and can be claimed. ACTIVE: You have already claimed this listing. BLOCKED: The listing has an existing relationship with n49.ca and may not be claimed. |
| name | The name of the listing returned |
| address | The street address of the result listing |
| address2 | Address line 2 for the result listing |
| sublocality | The sublocality (e.g., neighborhood or district) of the result listing |
| city | The city of the result listing |
| state | The state, region, or province of the result listing |
| zip | The ZIP or postal code of the result listing |
| countryCode | The country of the result listing (ISO 3166-1 alpha-2 code) |
| phone | The primary phone number of the listing. For international numbers, this number reflects how the number is dialed within the country (i.e., no country code or punctuation). |
| url | The URL where the listing’s details page can be viewed |
| rating | The current rating for the listing this is out of 10 |
| Star Rating | The aggregate rating for the business. This is restricted to the property value specifified in the URL Parameters. If no property was specified, this will be an aggregate of all reviews across all properties. |
| total_reviews | The total number of reviews for the listing |
| categories | An array of objects with categories of the result listing. Includes the cIDs and the name of the categories in the response. |
| website | The website associated with the result listing |
| description | The business description associated with the result listing |
| photos | Array of objects of photos associated with the result listing. Elements in the array are objects that have multiple properties such as height, width, type and src |
| yearEstablished | The year that the location opened (e.g., 1982) |
| specialOfferMessage | The "message" portion of the specialOffer if there is one |
| specialOfferUrl | The "URL" portion of the specialOffer if there is one |
| contact_email | The email address that consumers can use to contact a location representative |
| latitude | The latitude portion of the business's coordinates (for mapping purposes) |
| longitude | The longitude portion of the business's coordinates (for mapping purposes) |
| video | The URL of the business's videos |
| payment_options | A list of payment methods that the business accepts. |
| The business's Twitter username | |
| The URL of business's Facebook Page |
#Examples
{
"id": "888303",
"status": "AVAILABLE",
"name": "N49.ca",
"address": "505 Eglinton Ave. W",
"address2": "Suite 402",
"sublocality": "Forest Hill (and Forest Hill Village)",
"city": "Toronto",
"state": "ON",
"zip": "M5N 1B1",
"countryCode": "CA",
"phone": "4163852433",
"url": "http://www.n49.ca/biz/n49ca/on/toronto/505-eglinton-ave-w/",
"rating": 7.8,
"total_reviews": 11,
"categories": [
{
"cid": "2810",
"name": "Directory Advertising Service providers"
}
],
"website": "http://www.n49.ca",
"description": "Local Reviews Across Canada",
"photos": null,
"yearEstablished": "2001",
"specialOfferMessage": null,
"specialOfferUrl": null,
"contact_email": "rick@n49.com",
"latitude": "43.7034153225",
"longitude": "-79.4135378393",
"video": null,
"payment_options": null,
"twitter": null,
"facebook": null
}