API Documentation
Locations and Listings¶
In Metro Publisher, you can create locations and "attach" them to, for example, reviews and events.
With the Directory Add-On, locations can become listings. Listings have additional information regarding the location, such as a coupon (e.g. a restaurant coupon for the website user to print out in order to receive discounts the next time they eat at that restaurant).
Goal¶
In this chapter, we will add two locations and one listing to the MP instance:
- Location
- title: Thai Chi
- uuid: aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
- Location
- title: Viet Pho
- uuid: bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb
- Listing
- title: Happy Eatery
- uuid: cccccccc-cccc-cccc-cccc-cccccccccccc
Note
Listings are only available if the Metro Publisher instance has the Directory Add-On.
We'll enhance the second location (Viet Pho) later and make it into a listing.
Locations¶
Adding Locations¶
Let's create the first location, a restaurant that serves Thai food. We do this by sending a request to PUT /{iii}/locations/{uuid} with the following data:
>>> PUT("/123/locations/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
... {"urlname": "thai-chi",
... "title": "Thai Chi",
... "description": "Thai Chi serves a wide variety of Thai food.",
... "state": "published",
... "created": "2012-08-12T10:00:00",
... "modified": "2012-08-12T10:00:00",
... "street": "Main St.",
... "streetnumber": "234c",
... "pcode": "12345",
... "geoname_id": 2643743,
... "coords": [51.51184, -0.11087],
... "phone": "(123) 45678",
... "email": "info@thai-chi.co.uk",
... "website": "http://www.thai-chi.co.uk",
... "opening_hours": """Sun-Thu 2pm-11pm\nFri+Sat 2pm-1am""",
... "thumb_uuid": "22222222-2222-2222-2222-222222222222"})
{'url': 'https://api.metropublisher.com/123/locations/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'}
The data we sent can be divided into several components:
General Information
urlname, title, description, state, created and modidfied are fields that apply to most objects in Metro Publisher
Address Information
street, streetnumber, pcode (postal/zip code) and geoname_id (see GeoNames)
Map Information
coords is the location's point on a map (latitude/longitude)
Additional Information
phone, email, website and opening_hours (see /{iid}/locations/{uuid} for more information on additional location-specific fields)
thumb_uuid is a thumbnail for the location. The image must already exist in the Metro Publisher instance, i.e. it has to be added before it can be attached to the location.
Let's add the second loction:
>>> PUT("/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
... {"urlname": "viet-pho",
... "title": "Viet Pho",
... "description": None,
... "state": "published",
... "created": "2012-08-12T10:00:00",
... "modified": "2012-08-12T10:00:00",
... "street": "Main St.",
... "streetnumber": "433",
... "sort_title": None,
... "pcode": "12349",
... "geoname_id": 2643743,
... "coords": [51.51279, -0.09184],
... "phone": "(123) 87654",
... "website": "http://www.viet-pho.co.uk",
... "opening_hours": """Mon-Sun 5pm-1am"""})
{'url': 'https://api.metropublisher.com/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
'uuid': 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'}
Retrieving a List of Locations¶
We send a request to GET /{iid}/locations to get a list of available locations. We can specify a number of fields to retrieve for each content object, such as the title and urlname of the object as well as the API url to the object:
>>> GET("/123/locations?fields=title-urlname-url")
{'items': [['Thai Chi',
'thai-chi',
'https://api.metropublisher.com/123/locations/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'],
['Viet Pho',
'viet-pho',
'https://api.metropublisher.com/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb']]}
As with other API collection resources, the list can be filtered and ordered. See /{iid}/locations for a list of available parameters.
Retrieving Location Information¶
To retrieve information regarding a specific location, send a GET request to the resource /{iid}/locations/{uuid}:
>>> GET("/123/locations/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa")
{'closed': False,
'content': None,
'coords': [51.51184, -0.11087],
'created': '2012-08-12T10:00:00',
'description': 'Thai Chi serves a wide variety of Thai food.',
'email': 'info@thai-chi.co.uk',
'fax': None,
'fb_headline': None,
'fb_show_faces': True,
'fb_show_stream': True,
'fb_url': None,
'geoname_id': 2643743,
'lat': 51.51184,
'location_types': [],
'long': -0.11087,
'modified': '2012-08-12T10:00:00',
'opening_hours': 'Sun-Thu 2pm-11pm\nFri+Sat 2pm-1am',
'pcode': '12345',
'phone': '(123) 45678',
'price_index': None,
'print_description': None,
'sort_title': None,
'state': 'published',
'street': 'Main St.',
'streetnumber': '234c',
'thumb_url': 'https://api.metropublisher.com/123/files/22222222-2222-2222-2222-222222222222',
'title': 'Thai Chi',
'twitter_username': None,
'urlname': 'thai-chi',
'uuid': 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
'website': 'http://www.thai-chi.co.uk'}
Listings (Directory Add-On)¶
Attention
The following resources/attributes are only available if the Metro Publisher instance has the Directory Add-On.
Adding Listings¶
A listing has the same attributes as a basic location. However, when a location is marked as a listing, additional listing-specific attributes can be set:
>>> PUT("/123/locations/cccccccc-cccc-cccc-cccc-cccccccccccc",
... {"urlname": "happy-eatery",
... "title": "Happy Eatery",
... "state": "published",
... "geoname_id": 2643743,
... "coords": [51.50278, -0.15278],
... "created": "2012-08-12T10:00:00",
... "modified": "2012-08-12T10:00:00",
... "is_listing": True,
... "sponsored": True,
... "contact_person": "Peter Parker",
... "contact_email": "peter@parker.com",
... "listing_start": "2014-03-05T15:30:00",
... "listing_expires": "2016-03-05T15:30:00",
... "coupon_img_uuid": "12345678-1234-1234-1234-123456789abc",
... "coupon_title": "Great Deal",
... "coupon_description": "Get a 10% discount on all noodle dishes.",
... "coupon_start": "2014-04-01T00:00:00",
... "coupon_expires": "2014-06-01T00:00:00"})
{'url': 'https://api.metropublisher.com/123/locations/cccccccc-cccc-cccc-cccc-cccccccccccc',
'uuid': 'cccccccc-cccc-cccc-cccc-cccccccccccc'}
In order to mark a location as a listing, we set the is_listing parameter to True. Now, the listing-specific parameters become available:
sponsored
Setting the sponsored parameter to True marks the listing as a sponsored listing. It will be highlighted in the directory.
contact_person, contact_email
These parameters define internal information about who to contact regarding the listing. This information is not displayed on the website and is only for internal (inside the Metro Publisher instance's publication) use.
listing_start, listing_expires
A listing can be restricted to a time frame, i.e. the location is only a listing (and only appears in the directory) between listing_start and listing_expires (expires is optional). After the date/time given in listing_expires, the listing reverts to a basic location, i.e. it will no longer appear in the directory.
coupon_img_uuid
This parameter identifies the coupon image within the Metro Publisher instance. The image file must be added first if it doesn't alredy exist.
The coupon_img_uuid is required in order to add/edit a listing coupon.
coupon_title, coupon_description
Both parameters are optional. The title and description appear next to the coupon image on the location's public webpage.
coupon_start, coupon_expires
Both parameters are optional. The coupon will only appear on the location's public webpage during the period marked by coupon_start and coupon_expires.
Retrieving a List of Listings¶
As seen in Retrieving a List of Locations, we can get the available locations by sending the following request to GET /{iid}/locations:
>>> GET("/123/locations?fields=title")
{'items': [['Happy Eatery'], ['Thai Chi'], ['Viet Pho']]}
The returned list contains both the location added in Adding Locations as well as the location/listing added in Adding Listings. The GET /{iid}/locations resource however takes the parameter type, which means we can filter the returned list as follows:
>>> GET("/123/locations?fields=title&type=listing")
{'items': [['Happy Eatery']]}
The standard locations no longer appear in the returned list.
To retrieve only locations that are not listings, send the following request:
>>> GET("/123/locations?fields=title&type=location")
{'items': [['Thai Chi'], ['Viet Pho']]}
If type is 'location', the returned list only contains the standard locations, not the listings. If type is 'sponsored', the returned list only contains the sponsored listings.
Note
type is only available if the instance has the Directory Add-On!
Retrieving Listing Information¶
If the instance has the Directory Add-On, the resource GET /{iid}/locations/{uuid} returns the standard location information as well as the listing-specific information, independend of whether the location is a listing or not:
>>> GET("/123/locations/cccccccc-cccc-cccc-cccc-cccccccccccc")
{'closed': False,
'contact_email': 'peter@parker.com',
'contact_person': 'Peter Parker',
'content': None,
'coords': [51.50278, -0.15278],
'coupon_description': 'Get a 10% discount on all noodle dishes.',
'coupon_expires': '2014-06-01T00:00:00',
'coupon_img_url': 'https://api.metropublisher.com/123/files/12345678-1234-1234-1234-123456789abc/download/1346140800',
'coupon_img_uuid': '12345678-1234-1234-1234-123456789abc',
'coupon_start': '2014-04-01T00:00:00',
'coupon_title': 'Great Deal',
'created': '2012-08-12T10:00:00',
'description': None,
'email': None,
'fax': None,
'fb_headline': None,
'fb_show_faces': True,
'fb_show_stream': True,
'fb_url': None,
'geoname_id': 2643743,
'is_listing': True,
'lat': 51.50278,
'listing_expires': '2016-03-05T15:30:00',
'listing_start': '2014-03-05T15:30:00',
'location_types': [],
'long': -0.15278,
'modified': '2012-08-12T10:00:00',
'opening_hours': None,
'pcode': None,
'phone': None,
'price_index': None,
'print_description': None,
'sort_title': None,
'sponsored': True,
'state': 'published',
'street': None,
'streetnumber': None,
'thumb_url': None,
'title': 'Happy Eatery',
'twitter_username': None,
'urlname': 'happy-eatery',
'uuid': 'cccccccc-cccc-cccc-cccc-cccccccccccc',
'website': None}
The attribute is_listing let's us know whether the location is a listing or not. Even if is_listing is True, the listing may not appear as such on the website. It only appears as a listing within the time frame defined by listing_start and listing_expires.
Modifying Specific Attributes of a Location/Listing¶
When we added the second location (Viet Pho) earlier, we added an empty description and no price index:
>>> GET("/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb")
{'closed': False,
'content': None,
'coords': [51.51279, -0.09184],
'created': '2012-08-12T10:00:00',
'description': None,
'email': None,
'fax': None,
'fb_headline': None,
'fb_show_faces': True,
'fb_show_stream': True,
'fb_url': None,
'geoname_id': 2643743,
'lat': 51.51279,
'location_types': [],
'long': -0.09184,
'modified': '2012-08-12T10:00:00',
'opening_hours': 'Mon-Sun 5pm-1am',
'pcode': '12349',
'phone': '(123) 87654',
'price_index': None,
'print_description': None,
'sort_title': None,
'state': 'published',
'street': 'Main St.',
'streetnumber': '433',
'thumb_url': None,
'title': 'Viet Pho',
'twitter_username': None,
'urlname': 'viet-pho',
'uuid': 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
'website': 'http://www.viet-pho.co.uk'}
We want to correct that oversight now by modifying the location's description and adding price information. However, we don't want to send the entire location data again, just the two adjusted attributes. We do that by sending the following request to PATCH /{iid}/locations/{uuid}:
>>> PATCH("/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
... {'description': 'Viet Pho serves specialties from Vietnam.',
... 'price_index': "moderate"})
{'url': 'https://api.metropublisher.com/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
'uuid': 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'}
Let's check that the two fields were changed:
>>> GET("/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb")
{'closed': False,
'content': None,
'coords': [51.51279, -0.09184],
'created': '2012-08-12T10:00:00',
'description': 'Viet Pho serves specialties from Vietnam.',
'email': None,
'fax': None,
'fb_headline': None,
'fb_show_faces': True,
'fb_show_stream': True,
'fb_url': None,
'geoname_id': 2643743,
'lat': 51.51279,
'location_types': [],
'long': -0.09184,
'modified': '2012-08-12T10:00:00',
'opening_hours': 'Mon-Sun 5pm-1am',
'pcode': '12349',
'phone': '(123) 87654',
'price_index': 'Moderate',
'print_description': None,
'sort_title': None,
'state': 'published',
'street': 'Main St.',
'streetnumber': '433',
'thumb_url': None,
'title': 'Viet Pho',
'twitter_username': None,
'urlname': 'viet-pho',
'uuid': 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
'website': 'http://www.viet-pho.co.uk'}
The PATCH /{iid}/locations/{uuid} resource can also be used to make a standard location into a listing:
>>> PATCH("/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
... {'is_listing': True})
{'url': 'https://api.metropublisher.com/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
'uuid': 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'}
Note
Marking a location as a listing via the PATCH resource only works if the instance has the Directory Add-On.
Please note that patching other listing/coupon data requires that the parameter is_listing is also passed and set to true:
>>> PATCH("/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
... {'is_listing': True,
... 'sponsored': True})
{'url': 'https://api.metropublisher.com/123/locations/bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
'uuid': 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb'}