======
Models
======
Listing
-------
.. note::
The listing model can be returned as "short" listing. The "short" listing
is the base data plus phone numbers, but excluding all other additional elements.
Legend
~~~~~~
Base
Listing model without additional elements, except phone numbers
REQ
Fields which are REQUIRED for update/create requests
.. list-table::
:header-rows: 1
:widths: 20 5 5 60
* - Name
- Base
- REQ
- Description
* - id
- Yes
- No
- The Opendi ID for this listing. The ID will be returned by Opendi, there is no need to include it for update/create requests.
* - source_id
- Yes
- Yes
- Partner's internal unique ID which identifies the listing in the partner's system.
* - source_partner
- Yes
- No
- Shows the owner of the listing. Value is "opendi", if it is not claimed. It is the name of the requestor, if it is claimed by the requestor. It is "other" when it cannot be claimed.
* - claimed
- Yes
- No
- If yes, it is already claimed by a partner. If no, it is free for claiming. This field cannot be set by a partner and will be ignored.
* - name
- Yes
- Yes
- The name of the listing
* - address
- Yes
- Yes
- The street name and number
* - zip
- Yes
- Yes
- Postal/ZIP code
* - place
- Yes
- Yes
- City
* - show_address
- No
- No
- true/false to indicate if the address is visible to the public. Defaults to true.
* - country_code
- Yes
- Yes
- Country code
* - latitude
- Yes
- No
- Latitude
* - longitude
- Yes
- No
- Longitude
* - keywords
- No
- No
- An array of keywords
* - description
- No
- No
- Informational text describing the business.
* - emails
- No
- No
- List of Email elements
* - phone
- Yes
- No
- List of Phone elements
* - url
- Yes
- No
- Full URL at which the listing can be viewed
* - hours
- No
- No
- Element of type Opening Hours.
* - images
- No
- No
- Element of type Image. Will be ignored in update/create requests.
* - links
- No
- No
- List of Links
* - categories
- No
- No
- A list of Category models.
* - active
- No
- No
- Set to false when the listing is suppressed, and true when it is not.
Populated by Opendi.
* - contact
- No
- No
- Contact person of type Person. Usually the person responsible for this listing. The partners contact data will be used if omitted.
Example
~~~~~~~
If you request a listing by issuing: **GET /de/listings/6433484**
You might get the following result:
.. code-block:: javascript
{
"id": "6433484",
"source_id": "123456",
"source_partner": "other",
"name": "Opendi AG",
"address": "40 Müllerstr.",
"zip": "80469",
"place": "München",
"country_code": "DE",
"latitude": 48.1312973,
"longitude": 11.5699438,
"keywords": [
"Contacts",
"White Pages",
"Yellow Pages",
"Telephonenumbers",
"Nice People"
],
"description": "A company full of nice people creating internet based white pages and and yellow pages.",
"emails": [
{
"id": "2137356",
"address": "a.stahl@opendi.com"
}
],
"phones": [
{
"id": "10297929",
"type": "landline",
"number": "+498001055105"
},
{
"id": "10297930",
"type": "landline",
"number": "+4989189476620"
},
{
"id": "10297931",
"type": "fax",
"number": "+4989189476626"
}
],
"url": "http://muenchen.de-eu-staging.opendi.com/6433484.html",
"hours": {
"monday": [
{
"start": "09:00:00",
"end": "17:00:00"
}
],
"tuesday": [
{
"start": "09:00:00",
"end": "17:00:00"
}
],
"wednesday": [
{
"start": "09:00:00",
"end": "17:00:00"
}
],
"thursday": [
{
"start": "09:00:00",
"end": "17:00:00"
}
],
"friday": [
{
"start": "10:00:00",
"end": "12:00:00"
},
{
"start": "14:00:00",
"end": "17:00:00"
}
],
"saturday": [],
"sunday": []
},
"images": [
{
"id": "1591",
"type": "logo",
"url": "http://static.opendi.com/yellow/local/de/6433484/images/1591.jpg",
"base64": null,
"caption": "Opendi logo"
}
],
"links": [
{
"id": "2137357",
"type": "website",
"url": "www.stadtbranchenbuch.com",
"display": "Stadt Branchenbuch"
},
{
"id": "2137358",
"type": "googleplus",
"url": "https://plus.google.com/118150864364347134043/",
"display": "https://plus.google.com/118150864364347134043/"
}
],
"categories": [
{
"id": "58",
"name": "Bestatter"
}
],
"active": true,
"contact": {
"id": "255846",
"name": "Christian",
"surname": "Grobmeier",
"title": "Sir",
"gender": "M"
}
}
Person
------
A person.
========= ====== ========================================= ===============
Name Req? Description Example
========= ====== ========================================= ===============
id No Unique Person ID, populated by Opendi. 123
name Yes The name of the person Christian
surname Yes The surname of the person Grobmeier
title No A title the person holds Dr., Engineer
gender No The gender, used for correct salutation M, F, U
========= ====== ========================================= ===============
Possible Gender types:
====== =====================
Type Description
====== =====================
M Male
F Female
U Unknown, Undefined
====== =====================
Phone
-----
A public phone contact.
======== ====== ======================================= ===========
Name Req? Description Example
======== ====== ======================================= ===========
id No Unique phone ID, populated by Opendi. 123
type Yes Phone type as stated below mobile
number Yes Phone number in E.164 format +49123456
label No Freetext describing this number Secretary
======== ====== ======================================= ===========
Possible Phone types:
========== ====================
Type Description
========== ====================
landline Landline number
mobile Mobile number
fax Fax number
tollfree Toll free number
========== ====================
Email
-----
An Email contact.
========= ====== ======================================= =================
Name Req? Description Example
========= ====== ======================================= =================
id No Unique email ID, populated by Opendi. 123
address Yes Email address info@opendi.com
========= ====== ======================================= =================
Opening Hours
-------------
Opening hours of this business.
Each day may have multiple intervals when the business is open. This allows for
breaks in the opening hours.
Opening hours are send in the ISO 8601 format. The format allows the time to become
24:00, when the end of the day is meant. In example, a listing opened for 24 hours
has the opening time 00:00 - 24:00.
A listing having the time 00:00 - 00:00 would mean it is not open at all.
It is not supported to send day spanning intervals. In example, MO 14:00 - 02:00 would
not be accepted as the end time is before the start time. Supporting such formats
would lead to several issues, like there is no way to tell if 02:00 would be actually
tuesday or not wednesday. Also, the 02:00 could by a mistake where the sender
mixed up start and end time. Finally we cannot say for sure if 00:00 to 00:00 is
not actually meaning the shop is closed.
A time span from MO 15:00 - 02:00 (tuesday) needs to be send as an interval of
MO 15:00 - 24:00 and TU 00:00 - 02:00.
============ ====== ========================================== =================
Name Req? Description Example
============ ====== ========================================== =================
monday No A list of Opening Hours Interval models.
tuesday No A list of Opening Hours Interval models.
wednesday No A list of Opening Hours Interval models.
thursday No A list of Opening Hours Interval models.
friday No A list of Opening Hours Interval models.
saturday No A list of Opening Hours Interval models.
sunday No A list of Opening Hours Interval models.
text No Text with additional opening hours info. By appointment.
============ ====== ========================================== =================
At least one day, or the ``text`` field should be set when specifying this
element.
Example including Intervals:
.. code-block:: javascript
{
"monday": [
{
"start": "10:00",
"end": "11:00"
},
{
"start": "14:00",
"end": "15:00"
}
],
"tuesday": [
{
"start": "10:00",
"end": "11:00"
},
{
"start": "14:00",
"end": "15:00"
}
],
"text": "We also work by appointment. Call us to schedule."
}
Opening Hour Interval
---------------------
Interval within the day for opening hours. Uses ISO 8601 time format (`hh:mm` or
`hh:mm:ss`).
.. list-table::
:header-rows: 1
* - Name
- Req?
- Description
- Example
* - start
- Yes
- Start of the interval
- 10:00
* - end
- Yes
- Ending of the interval
- 11:00
Offer
-----
A special offer from the listings owner. In example, a promotional message
with an optional URL.
============= ====== =========================================== ===============
Name Req? Description Example
============= ====== =========================================== ===============
message Yes A promotional message Today 50% off
url No A protocol prefixed url
============= ====== =========================================== ===============
Example:
.. code-block:: javascript
{
"message": "Today 50% off to each Pizza",
"url": "http://www.example.com/specialoffer"
}
Image
-----
An image representing the listing.
Opendi will generate thumbnails and resized versions from uploaded images.
Currently the maximum image size used is 1200x1200px. This is matter
to change without prior warning. The maximum upload payload is 4 MB.
When uploading an image, populate the **base64** field with Base 64 encoded
image data. This field will not be populated when retrieving an image.
======= ====== ======================================= ============
Name Req? Description Example
======= ====== ======================================= ============
id No Unique image ID, populated by Opendi 123
type Yes Type of image, see list below logo
url No Image URL, populated by Opendi
base64 Yes Base64 encoded image data
caption No Caption for this image Cool image
======= ====== ======================================= ============
Possible image types:
========== ========================
Type Description
========== ========================
logo Business logo
gallery A gallery image
printad A printed advertisment
========== ========================
An example with base64 encoded image data:
.. code-block:: javascript
{
"type": "logo"
"base64": "VGhpcyBpcyBwcmV0ZW5kaW5nIHRvIGJlIGFuIGltYWdlLg=="
}
An example for requesting an already created image:
.. code-block:: javascript
{
"id": "15662346676"
"type": "logo"
"url": "http://static.opendi.com/images/hello.jpg"
}
Review
------
A customer review.
============ ====== ======================================= ===========================
Name Req? Description Example
============ ====== ======================================= ===========================
id No Unique review ID, populated by Opendi 123
source_id Yes Partner's internal unique review ID 321
reviewer Yes Name of the person writing the review John Doe
reviewed No Name of the reviewed entity, used when Pizzeria
there are several entities within the
same listing.
title Yes The review title Great pizza!
text No Full review text
rating Yes Review rating, 1-5 where 5 is best 3
review_url
listing_url
date_time No The date and time when the review was 2015-02-16T17:38:56+02:00
given (defaults to current datetime)
============ ====== ======================================= ===========================
The datetime format used in ``date_time`` is defined in `RFC3339`_, section 5.6.
It should contain the full date, time and timezone.
.. _RFC3339: https://www.ietf.org/rfc/rfc3339.txt
Link
----
A link to a web page.
======= ====== ======================================= ====================
Name Req? Description Example
======= ====== ======================================= ====================
id No Unique link ID, populated by Opendi 123
type Yes Type of Link, see list below website
url Yes The full URL to the webpage http://opendi.com
display No The link text / title. Opendi homepage
======= ====== ======================================= ====================
Allowed Link types:
============== =================================================================================
Type Description
============== ========================
facebook Facebook
googleplus Google plus
linkedin Linkedin
menu Restaurant menu page
order Order page
reservations Reservations page
twitter Twitter
website Web site
xing Xing
video Video: An actual video, in example: https://www.youtube.com/watch?v=Ep__vi4Dvf0
youtube A YouTube channel, in example: https://www.youtube.com/user/TheApacheFoundation
============== =================================================================================
Example:
.. code-block:: javascript
{
"type": "facebook",
"url": "http://www.facebook.de/opendiAG",
"display": "Opendi facebook page"
}
Category
--------
A listing category.
.. list-table::
:header-rows: 1
* - Name
- Req?
- Description
* - id
- Yes
- Unique ID of the category
* - name
- Yes
- Name of the category
Example:
.. code-block:: javascript
{
"id": "50",
"name": "Window Cleaners"
}
Mapping
-------
A mapping between a Partner's listing ID and Opendi's listing ID.
============= ====== =========================================== ===============
Name Req? Description Example
============= ====== =========================================== ===============
source_id Yes Partner's unique ID. 12345
opendi_id Yes Corresponding Opendi's unique listing ID. 54321
============= ====== =========================================== ===============
Partner provides a source_id when creating a listing.
Example:
.. code-block:: javascript
{
"source_id": "12345",
"opendi_id": "54321"
}
Error
-----
Returned in case of an error.
.. list-table::
:header-rows: 1
* - Name
- Req?
- Description
* - type
- Yes
- The error type, see below
* - message
- Yes
- Human readable error message
* - details
- No
- An additional array of errors, e.g. validation errors
Possible error types:
.. list-table::
:header-rows: 1
* - Name
- Description
* - bad_request
- Your request contained an error.
* - blacklist
- Trying to modify a blacklisted listing
* - internal
- An unspecified internal error occurred. Please contact support.
* - validation
- Model validation failed.
Example:
.. code-block:: javascript
{
"type": "validation",
"message": "Validation failed for Listing model",
"details": [
"'id' field must be an integer, string given",
"'zip' field must be numeric"
]
}