Applications in Modyo create digital resources that can be served to the front end for developers through JSON objects.
In this article:
JSON is an open-standard file format that transmits human-readable data over the internet. JSON objects in Modyo have sets of properties with a name and a value. For example, the JSON object for a Post made in the Content application has properties such as:
{ ... title: "Learn more about your financial options", tags: [ financial, education ], category: "Featured", published_at: "2017-10-16T11:30:17.000-03:00", ... }
Developers use the information provided in these objects to create rich SPAs, widgets, and responsive layouts and pages.
The MIME media type for JSON text is application/json
. This documentation details the types of JSON objects that Modyo generates, as well as the different parameters they accept.
Object Types
Modyo uses 10 different object types, made in the following applications:
JSON Object Name | Modyo Application |
Media | Content |
Posts | Content |
Albums | Content |
Videos | Content |
Audio | Content |
Files | Content |
Promotions | Promotions |
Locations | Promotions |
Places | Places |
Locations | Places |
Retrieve a paginated list
To return a paginated list of all objects of a given type, use the following format:
http://accountname.modyo.cloud/sitename/objectname.json |
Retrieve a single entry
It is also possible to return JSON objects individually for Promotions and Products. For example:
http://accountname.modyo.cloud/sitename/products/promotionslug.json |
Individual promotions and products contain additional information not found in their respective index returns (promotions.json
).
For example, when creating a promotion, marketers and content creators can add custom fields to promotions, but these custom fields are only available in individual promotion objects, not in the main promotions.json
.
Meta Property
Every JSON object comes with a meta property that displays the following information:
[ ... meta: { total_entries: 22, per_page: 12, current_page: 1, total_pages: 2 } ]
Parameters can change the total number of entries per page, or access specific pages.
Objects and Categories
In the Parameters section, there are many ways to sort and filter the information returned from a query. But, another way developers can return a list of JSON objects is by taking advantage of resource Categories.
To return all resources of a certain type that only match a specific category, you can insert the category name in the path portion of your URL, for example:
http://accountname.modyo.cloud/sitename/category/media.json |
This will return all posts, albums, video, audio, and files that match the given category.
You can also return lists of objects matching one or more categories with queries.
Object Examples
Below is a list of JSON object examples by type.
Media.json
Media JSON objects in Modyo come in 5 different subtypes: Posts, Albums, Video, Audio, and Files.
Using media.json
will return all five types of the following:
Posts.json
posts: [ { id: 34647, uuid: "0789a753-a728-4745-bb2a-56ec7a00f26e", created_at: "2017-08-03T14:01:21.000-03:00", updated_at: "2017-08-03T14:01:21.000-03:00", published_at: "2017-10-16T11:30:17.000-03:00", url: "https://accountname.modyo.cloud/site-name/featured/posts/post-name", title: "Post Title", slug: "post-title", description: "<p>Post description/content</p>", covers: [ "https://cloud.modyocdn.com/uploads/b58f4528-f615-4b12-a5dc-11b54162ca44/original/samplecover.png" ], tags: [ "tag1", "tag2", "tag3" ], category: "featured", site_id: 920, options: { }, video_url: "" }, ]
Albums.json
albums: [ { id: 34772, uuid: "51bae32a-8f6f-4806-b5b9-30de7b3bed4e", created_at: "2017-11-28T15:30:45.000-03:00", updated_at: "2017-11-28T15:30:45.000-03:00", published_at: "2017-10-16T11:30:17.000-03:00", url: "https://accountname.modyo.cloud/site-name/articles/albums/sample-album", title: "Sample Album", slug: "sample-album", description: "<p>Album description</p>", covers: [ "https://cloud.modyocdn.com/uploads/c6ce48f6-702b-4bd8-be37-118cd835c27d/original/modyologo-m.png" ], tags: [ "tag1", "tag2", "tag3" ], category: "articles", site_id: 920, options: { }, video_url: "", pictures: [ "https://cloud.modyocdn.com/uploads/d23f16eb-1bf9-43aa-bf81-f8446b7ef590/original/demo-screenshot-1.png", "https://cloud.modyocdn.com/uploads/e909c85b-9859-4091-8fd2-8a01fa204efd/original/demo-screenshot-2.png", "https://cloud.modyocdn.com/uploads/b1122bf3-253d-49d5-bc87-d67d1c38ce36/original/demo-screenshot-3.png" ] } ],
Videos.json
videos: [ { id: 34773, uuid: "40bd89b7-c15e-4938-94c4-e2eb01da4571", created_at: "2017-11-28T15:56:39.000-03:00", updated_at: "2017-11-28T15:56:39.000-03:00", published_at: "2017-12-16T11:30:17.000-03:00", url: "https://accountname.modyo.cloud/site-name/featured/videos/sample-video", title: "Sample Video", slug: "sample-video", description: "<p>Video description</p>", covers: [ "https://cloud.modyocdn.com/uploads/5cb91b86-7a8e-4553-bb4a-3b067c6b615f/original/modyologo-m.png" ], tags: [ "tag1", "tag2", "tag3" ], category: "featured", site_id: 920, options: { }, video_url: "https://cloud.modyocdn.com/uploads/78a03131-b5d6-4a12-b697-5f4f16b6d9f0/original/Corona_-_Rhythm_of_the_Night.mp4", video: "https://cloud.modyocdn.com/uploads/78a03131-b5d6-4a12-b697-5f4f16b6d9f0/original/Corona_-_Rhythm_of_the_Night.mp4" } ],
Audio.json
audio: [ { id: 34774, uuid: "30bbaa26-6f2b-49b9-9eaf-671a097d5a57", created_at: "2017-11-28T16:03:48.000-03:00", updated_at: "2017-11-28T16:03:48.000-03:00", published_at: "2017-12-16T11:30:17.000-03:00", url: "https://accountname.modyo.cloud/site-name/featured/audio/audio-sample", title: "Audio Sample", slug: "audio-sample", description: "<p>Audio description</p>", covers: [ "https://cloud.modyocdn.com/uploads/b1245ea4-59bb-44df-aadb-e17aa29a6599/original/modyologo-m.png" ], tags: [ "tag1", "tag2", "tag3" ], category: "featured", site_id: 920, options: { }, video_url: "", audio: "https://cloud.modyocdn.com/uploads/f1bc03cf-8c78-408e-91f4-28a052c8ed5e/original/Bach_Cello_Suite_No_1_-_Prelude_Yo-Yo_Ma_.mp3" } ],
Files.json
files: [ { id: 34777, uuid: "db2d571d-2441-417f-ad16-95c1dc8f5aa3", created_at: "2017-11-28T16:40:22.000-03:00", updated_at: "2017-11-28T16:40:22.000-03:00", published_at: "2017-12-16T11:30:17.000-03:00", url: "https://accountname.modyo.cloud/site-name/featured/files/sample-file", title: "Sample File", slug: "sample-file", description: "<p>File description/content</p>", covers: [ "https://cloud.modyocdn.com/uploads/1ab0a684-642c-47bb-b202-45085e36b9a6/original/modyologo-m.png" ], tags: [ "tag1", "tag2", "tag3" ], category: "featured", site_id: 920, options: { }, video_url: "", file: "https://cloud.modyocdn.com/uploads/5809chfe-59a2-4d40-88fb-0f1e10f26cd1/original/Sample.pdf" } ],
There are some differences between the media.json
, object types, such as albums.json
objects having a picture array, files.json
objects having a file property, etc. But overall, most properties of these objects are the same.
Promotions.json
promotions.json
objects have similar properties to media.json
, but when accessed individually (through the resource slug), they display more information such as multiple locations, and custom fields.
promotions: [ { id: 191, uuid: "94998388-2146-463f-ae0a-195294925d73", created_at: "2017-11-28T17:14:11.000-03:00", updated_at: "2017-11-28T17:14:11.000-03:00", published_at: "2017-12-16T11:30:17.000-03:00", url: "https://accountname.modyo.cloud/site-name/featured/promotions/sample-promotion", title: "Sample Promotion", slug: "sample-promotion", excerpt: "Sample exerpt", description: "<p>Sample description/content</p>", covers: [ "https://cloud.modyocdn.com/uploads/58f5665a-53d4-45d7-b9d7-1749be97324a/original/cine-christmas.jpg" ], tags: [ "tag1", "tag2", "tag3" ], category: "featured", site_id: 920, conditions: "Sample conditions", start_date: "2017-11-30T00:00:43.000-03:00", end_date: "2017-12-30T08:00:56.000-03:00", discount: 15, location_street: "Bicentenario 3883, Vitacura, Chile", latitude: "-33.398296", longitude: "-70.60051170000003" } ]
This sample above displays basic information about a promotions.json
object (such as the first address entry in the location_street property). But this is just one of many objects in a returned index. When we access this same promotion specifically, we can retrieve more information:
Promotions/sample-promotion.json
{ id: 191, uuid: "94998388-2146-463f-ae0a-195294925d73", created_at: "2017-11-28T17:14:11.000-03:00", updated_at: "2017-11-28T17:14:11.000-03:00", url: "https://accountname.modyo.cloud/site-name/featured/promotions/sample-promotion", title: "Sample Promotion", slug: "sample-promotion", excerpt: "Sample exerpt", description: "<p>Sample description/content</p>", covers: [ "https://cloud.modyocdn.com/uploads/58f5665a-53d4-45d7-b9d7-1749be97324a/original/cine-christmas.jpg" ], tags: [ "tag1", "tag2", "tag3" ], category: "featured", site_id: 920, conditions: "Sample conditions", start_date: "2017-11-30T00:00:43.000-03:00", end_date: "2017-12-30T08:00:56.000-03:00", discount: 15, location_street: "Bicentenario 3883, Vitacura, Chile", latitude: "-33.398296", longitude: "-70.60051170000003", locations: [ { id: 411, location_street: "Bicentenario 3883, Vitacura, Chile", latitude: "-33.398296", longitude: "-70.60051170000003", country: "Chile", administrative_area_level_1: "Región Metropolitana", administrative_area_level_2: "Santiago", administrative_area_level_3: "Vitacura", administrative_area_level_4: null, administrative_area_level_5: null }, { id: 412, location_street: "Costanera Center, Providencia, Chile", latitude: "-33.4179935", longitude: "-70.6063901", country: "Chile", administrative_area_level_1: "Región Metropolitana", administrative_area_level_2: null, administrative_area_level_3: "Providencia", administrative_area_level_4: null, administrative_area_level_5: null }, { id: 413, location_street: "Avenida Holanda 87, Providencia, Chile", latitude: "-33.4201193", longitude: "-70.6041444", country: "Chile", administrative_area_level_1: "Región Metropolitana", administrative_area_level_2: "Santiago", administrative_area_level_3: "Providencia", administrative_area_level_4: null, administrative_area_level_5: null } ], custom_fields: { customString: { id: 18, value: "String value" }, customNumber: { id: 19, value: 10 }, customBoolean: { id: 20, value: true } } }
Notice the promotion_fields property. This is a list of custom fields added to the Promotions application by content creators. These can be used to customize any content needed for a promotion.
The other larger property is locations. This property contains all locations where this promotion is available. The information in locations is formatted so that front end developers can easily feed the data to Google Maps, for example, and add value to every promotion built within the platform.
In fact, geolocation data is so valuable, Modyo has a separate locations.json
pthat returns all location data in a single index for both Promotions and Places:
Locations.json
locations: [ { id: 411, location_street: "Bicentenario 3883, Vitacura, Chile", latitude: "-33.398296", longitude: "-70.60051170000003", country: "Chile", administrative_area_level_1: "Región Metropolitana", administrative_area_level_2: "Santiago", administrative_area_level_3: "Vitacura", administrative_area_level_4: null, administrative_area_level_5: null, promotion: { id: 191, uuid: "94998388-2146-463f-ae0a-195294925d73", created_at: "2017-11-28T17:14:11.000-03:00", updated_at: "2017-11-28T17:14:11.000-03:00", url: "https://accountname.modyo.cloud/site-name/featured/promotions/sample-promotion", title: "Sample Promotion", slug: "sample-promotion", excerpt: "Sample exerpt", description: "<p>Sample description/content</p>", covers: [ "https://cloud.modyocdn.com/uploads/58f5665a-53d4-45d7-b9d7-1749be97324a/original/cine-christmas.jpg" ], tags: [ "tag1", "tag2", "tag3" ], category: "featured", site_id: 920, conditions: "Sample conditions", start_date: "2017-11-30T00:00:43.000-03:00", end_date: "2017-12-30T08:00:56.000-03:00", discount: 15, promotion_fields: { customString: { id: 18, value: "String value" }, customNumber: { id: 19, value: 10 }, customBoolean: { id: 20, value: true } } } }, ]
The Promotions and Places applications each generate their own locations.json
and so the index of location objects can be accessed at:
http://accountname.modyo.cloud/sitename/promotions/locations.json or http://accountname.modyo.cloud/sitename/places/locations.json |
This sample is just one entry, but notice that the location object has a related promotion object inside. In this way, locations.json
allows geolocation data to be prioritized in a single index that developers can use to create maps with multiple promotion locations at the same time.
Places.json
The places.json
object array returns a list of simple locations like the following:
places: [ { id: 275, uuid: "d8d737e3-1b7a-4800-b8ba-30a691e8e7b0", created_at: "2018-02-12T18:04:23.000-03:00", updated_at: "2018-02-12T18:04:23.000-03:00", published_at: "2018-02-12T18:08:43.000-03:00", url: "https://demos.modyo.cloud/platypus-rocker/places/theres-no-place-like-home", title: "There's no place like home", slug: "theres-no-place-like-home", excerpt: "This is the excerpt of there's no place like home.", description: "Dorothy Gale: Oh, you're the best friends anybody ever had. And it's funny, but I feel as if I'd known you all the time, but I couldn't have, could I? The Scarecrow: I don't see how. You weren't around when I was stuffed and sewn together, were you? The Tin Woodsman: And I was standing over there, rusting for the longest time. Dorothy Gale: Still, I wish I could remember, but I guess it doesn't matter anyway. We know each other now, don't we?", covers: [ ], tags: [ ], category: null, site_id: 888, address: "Kansas, USA", latitude: "39.011902", longitude: "-98.48424649999998" } ],
These objects can be used and sorted with parameters to deliver geolocation data for map applications such as Google Maps. Each Places resource also has a related locations.json
entry, similar to Promotions. The only exception is a naming convention: the relevant places information in any given entry in locations.json
is labeled localizable.
Parameters
Parameters are useful for refining the total number of returned entries, and sorting them by specific order when requesting a list of JSON objects from the platform.
Each parameter has a value, and all objects will match each value specified. Many objects accept very similar parameters, but there are some key differences/exceptions, based on the purpose of the resource type.
Format
To input one or more parameters add a query (?) after the resource type, and then add each parameter=value, separated by an ampersand (&):
Meta Parameters
These meta parameters help change total entries per page, and navigate page results:
Parameter | Value |
page | navigates to specified page number; number should be from 1 to total_pages. |
per_page / limit | limits the number of object entries per page. |
Media Object Parameters
Ordering
These parameters are for ordering or sorting the results of the returned query:
Parameter | Value |
order / order_by / sort_by | fields: title (equal to slug), published_at, created_at, slug, category; if none match, or the input value is invalid, the object index is ordered by published_at desc. |
asc | Boolean value; if true, orders by ascending; if false, orders by descending (this is the default if the asc parameter is not present) |
Filtering
These are the filter parameters available for the media.json
object:
Parameter | Value |
tags | Filters tag names; separate tag values with a comma (no space), e.g. tags=tag1,tag2,etc. |
query | Filters word/phrase found in the title or the description. |
category / category_id / categories | Filters object category. |
uuids | Filters object uuid. |
slug | Filters object slug. |
scope | Numeric value that filters the list by number of days since a resource was created, e.g. a value of 7 would filter all resources made in the last week. |
Examples
Order by category and filter by tags:
?sort_by=category&asc=true&tags=baby,boy,red
Order by title and filter by a query:
?sort_by=title&asc=true&query=modyo
Filter by uuid:
?uuids=4e04e670-3187-4a17-3e73-81ad843f8eb1
Filter by slug:
?slug=your-example-title-here
Order by published date and filter by all media made in the last 7 days:
?sort_by=published_at&asc=true&scope=7
Promotions Object Parameters
Ordering
These parameters are for ordering the results of the returned query:
Parametre | Value |
order / order_by / sort_by | fields: title (equal to slug), published_at, created_at, updated_at, slug, category, discount; if none match, or the input value is invalid, the object index is ordered by published_at desc. |
asc | Boolean value; if true, orders by ascending; if false, orders by descending (this is the default if the asc parameter is not present). |
Filtrar
These are the matching parameters available for the promotions.json
object:
Parametre | Value |
tags | Filters tag names; separate tag values with a comma (no space), e.g. tags=tag1,tag2,etc. |
query | Filters word/phrase found in the title or the description. |
category / category_id / categories | Filters object category. |
uuids | Filters object uuid. |
slug | Filters object slug. |
scope | Numeric value that filters the list by number of days since a resource was created, e.g. a value of 7 would filter all resources made in the last week. |
Examples
Order by discount and filter by tags and by all promotions made in the past 7 days:
?sort_by=discount&asc=true&tags=red,blue&scope=7
Locations Object Parameters
The locations.json
object exists within the promotions.json
and places.json
objects, with the following parameters:
Ordering
These parameters are for ordering the results of the returned query:
Parametre | Value |
sort_by | fields: geo_distance, localizable; accepts promotion values by prepending localizable in dot-notation before the value, e.g. sort_by=localizable.title. |
asc | Boolean value; if true, orders by ascending; if false, orders by descending (this is the default if the asc parameter is not present). |
Example
Filter by radius and sort by distance:
?latitude=-33.39818&longitude=-70.60043&radius=2&sort_by=geo_distance
Filtering
Parametre | Value |
country | Filter by country. |
query | Filter by administrative_area_level_1 to 5. By prepending localizable in dot-noation, filterpromotions by all available promotion fields in locations.json . Custom fields can be accessed with the following format: – promotion_field_string_values.field – promotion_field_numeric_values.field – promotion_field_boolean_values.field |
latitude, longitude, radius | 3 separate numeric values that establish a point and maximum distance to return a set of location objects; use in conjuction with sort_by=geo_distance to return a list of locations ordered by nearest proximity to the specified point. |
administrative_area_level_1 to 5 |
Level 1 indicates a first-order civil entity below the country level. In the US, these are states. Level 2 indicates a second-order civil entity below the country level. In In the US, these are counties. Levels 3 to 5 indicate minor civil divisions. These parameters match Google's geocoding. |
bbox[] | Filter by bounding box; this parameter allows delimiting an area by defining two points: bbox[]= top_left_latitude&bbox[]= top_left_longitude&bbox[]= bottom_right_latitude&bbox[]= bottom_right_longitude |
tag, tags[] | Filters tag names; with multiple tags, separate tag values by repeating the tags[] parameter, e.g. tags[]=tag1&tags[]=tag2 etc. |
locations.json
is different than in other JSON objects. use the tag for one or tags[] for multiple values.Examples
Order by title and filter by tag:
?sort_by=localizable.title&order=asc&tag=bebes
Order by slug and filter by the tags baby and electronics:
?sort_by=localizable.slug&order=asc&tags[]=bebes&tags[]=juguetes
Match by country and administrative_area_level_3:
?country=Chile&administrative_area_level_3=Vitacura
Use the query parameter to match by administrative_area_level:
?query=administrative_area_level_1:Región%20Metropolitana
Use the query parameter to match by id:
?query=localizable.id:21
Use the query parameter to match by promotion custom field:
?query=localizable.promotion_field_boolean_values.mastercard:true
Filter by bounding box:
?bbox[]=-33.3900575286746&bbox[]=-70.6113851776123&bbox[]=-33.41011109098255&bbox[]=-70.58494297790526
Filter by bounding box and by distance:
?latitude=-33.39818&longitude=-70.60043&sort_by=geo_distance&order=asc&bbox[]=-33.3900575286746&bbox[]=-70.6113851776123&bbox[]=-33.41011109098255&bbox[]=-70.58494297790526
Places Object Parameters
Ordering
These parameters are for ordering or filtering the results of the returned query:
Parametre | Value |
order | fields: title (equal to slug), published_at, created_at, updated_at, slug, category, discount; if none match, or the input value is invalid, the object index is ordered by published_at desc. |
asc | Boolean value; if true, orders the specified field value in "order" by ascending; if false, orders by descending (this is the default if the asc parameter is not present) |
Filtering
These are the parameters available for the places.json
object:
Parametre | Value |
tags | Filters tag names; separate tag values with a comma (no space), e.g. tags=tag1,tag2,etc. |
query | Filters word/phrase found in the title or the description. |
latitude, longitude, radius | 3 separate numeric values that establish a point and maximum distance to return a set of location objects. |
category / category_id / categories | Filters object category. |
uuids | Filters object uuid. |
slug | Filters object slug. |
Examples
Filter by radius and sort by slug:
?latitude=-33.39818&longitude=-70.60043&radius=2&order=slug&asc=true