JSON Objects

Avatar
Alex Stein
  • Updated

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 (&):

Screen_Shot_2018-05-02_at_5.21.29_pm.png 

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. 
Note 1: If radius is used in conjunction with bbox[], radius will take precedence.
Note 2: Tagging in 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 
Was this article helpful?
2 out of 2 found this helpful
Have more questions? Submit a request
Return to top

Articles in this section

Related articles