Audio

Richie Audio API Endpoints

Descriptions of endpoints for audio metadata

GET /books/feeds/v3/{tenant_name}/podcast_episode/{episode_uuid}.json

Get metadata of a podcast episode. Does not need authentication.

Example response

{
  "data": {
    "ad_tags": null,
    "analytics_data": null,
    "audio_duration": 151,
    "audio_length": 1209616,
    "audio_pkgs": {},
    "audio_sample": null,
    "audio_url": "https://appdata.richie.fi/audiobooks/Nelonen/3bda2fbd-1e86-4c49-a654-4219473c23fa/ced34f_Rock_Uutiset_101224.mp3",
    "author": "",
    "availability_periods": [
      {
        "end_date": "2099-12-31T23:59:59Z",
        "product": null,
        "start_date": "2024-12-10T14:00:00Z",
        "type": "free"
      }
    ],
    "cover_url": "https://data.richie.app/books-images/m/Nelonen/uploads/029eb1e78c_Kuuntelep_iv_nt_rkeimm_trock_uutiset_kuva.jpg",
    "description": "Rock Uutisissa tänään mm. Suomeen saapuva Scorpionsin juhlakiertue.",
    "guid": "2b06a1b3-8557-4032-a044-f80c382872f8",
    "h": null,
    "kind": "podcast_episode",
    "last_modified": "2024-12-10T14:00:43.948607Z",
    "original_article_url": "",
    "photo_author": "",
    "publication_date": "2024-12-10T14:00:00Z",
    "rankings": {
      "daily": null,
      "monthly": null,
      "weekly": null
    },
    "series_guid": "666a9c8d-9e5e-4bb7-b9f1-9fcc1418e4b7",
    "series_tags": [],
    "series_title": "Rock-uutiset",
    "source_type": "manual",
    "square_cover_url": null,
    "square_photo_author": null,
    "tags": [],
    "title": "Rock Uutiset 10.12."
  }
}

Schema of "data" (a podcast episode)

"data" follows the schema for a podcast episode, with some article compatibility fields left empty.

PropertyDescriptionValue
kindKind (type) of the resource."podcast_episode"
source_typeOrigin of the episode."rss", "manual" or "article"
guidIdentifier of the episode.UUID
series_titleTitle of the series episode belongs to.String
series_guidIdentifier of the series episode belongs to.UUID
authorEpisode author.String
original_article_urlOriginal article URL. Empty for actual podcast episodes.String
titleEpisode title.String
descriptionEpisode description.String
publication_dateEpisode's first publication date.String (a date)
last_modifiedLast time the metadata was updated.String (a date).
cover_urlURL for a cover picture.String (an HTTPS URL).
photo_authorAuthor of the related photo. Empty for actual podcast episodes.String
square_cover_urlURL for a cover picture, guaranteed to be square. Empty for actual podcast episodes.String (an HTTPS URL) or null.
square_photo_authorURL for a cover picture, guaranteed to be square. Empty for actual podcast episodes.String or null.
audio_urlPlayback URL for the main audio.String (an HTTPS URL).
audio_durationDuration of audio in seconds. 0 and null mean duration is unknown.Integer (incl. 0) or null.
audio_lengthContent length of audio file, in bytes. 0 means unknown length.Integer (incl. 0).
audio_sampleDetails of a free sample version for audio. Not available for all episodes.Object or null.
audio_sample.audio_urlPlayback URL for the sample version.String (an HTTPS URL) if audio_sample is an object.
audio_sample.audio_durationDuration of audio in seconds. 0 and null mean duration is unknown.Integer (incl. 0) or null if audio_sample is an object..
audio_sample.audio_lengthContent length of audio file, in bytes. 0 means unknown length.Integer (incl. 0) if audio_sample is an object..
audio_pkgsRichie-managed alternative format audio packages. Details agreed with integrators.Object, possibly empty.
availability_periodsTime frames during which the episode is available in given products.Array of objects (availability period objects).
availability_periods[n].productProduct slug.String or null.
availability_periods[n].productType of the product (free or paid)."free" or "paid".
availability_periods[n].productStart of episode's inclusion in the product.String (a date).
availability_periods[n].end_dateEnd of episode's inclusion in the product.String (a date).
rankingsPopularity rankings for the episode.Object
rankings.dailyDaily popularity for the episode, if applicable. Lower number means more popular.Integer or null.
rankings.weeklyWeekly popularity for the episode, if applicable. Lower number means more popular.Integer or null.
rankings.monthlyMonthly popularity for the episode, if applicable. Lower number means more popular.Integer or null.
series_tagsTenant-specific values agreed with the tenant, for the series episode belongs to.Array of strings.
tagsTenant-specific values agreed with the tenant, for the episode.Array of strings.
analytics_dataTenant-specific data carried for analytics purposes. Actual fields agreed with the tenant.Object or null.
ad_tagsTenant-specific data carried for ad purposes. Actual fields agreed with the tenant.Object or null.
hInternal hash code over the payload, not always set.String or null.

GET /books/feeds/v3/{tenant_name}/podcast_series/{series_uuid}.json

Get metadata of a podcast series and its episodes. Does not need authentication.

Example response

{
  "data": {
    "guid": "666a9c8d-9e5e-4bb7-b9f1-9fcc1418e4b7",
    "last_modified": "2024-12-20T11:13:11.974746Z",
    "rss_feed_url": "",
    "title": "Rock-uutiset",
    "author": "",
    "description": "Miltä bändiltä on tulossa uusi julkaisu? Entä minkä levyn julkaisusta tulee kuluneeksi 30 vuotta?\r\n \r\nPysy kartalla rock-musamaailman
käänteistä ja kuuntele Radio Rockin Rock-uutiset. Päivän tärkeimmät rock-uutiset toimittaa Laura Vähähyyppä.",
    "html_description": null,
    "link": "",
    "publication_date": "2024-12-20T07:00:00Z",
    "copyright": "",
    "publisher": "Sanoma",
    "tags": [],
    "categories": [
      "b5ebfbf5-a24e-499f-97e2-5b916173ef87",
      "215b6090-8df0-4d1a-b1d1-74b4f749d1dc"
    ],
    "episodes": [
      {
        "ad_tags": null,
        "analytics_data": null,
        "audio_duration": 151,
        "audio_length": 1209616,
        "audio_pkgs": {},
        "audio_sample": null,
        "audio_url": "https://appdata.richie.fi/audiobooks/Nelonen/3bda2fbd-1e86-4c49-a654-4219473c23fa/ced34f_Rock_Uutiset_101224.mp3",
        "author": "",
        "availability_periods": [
            {
                "end_date": "2099-12-31T23:59:59Z",
                "product": null,
                "start_date": "2024-12-10T14:00:00Z",
                "type": "free"
            }
        ],
        "cover_url": "https://data.richie.app/books-images/m/Nelonen/uploads/029eb1e78c_Kuuntelep_iv_nt_rkeimm_trock_uutiset_kuva.jpg",
        "description": "Rock Uutisissa tänään mm. Suomeen saapuva Scorpionsin juhlakiertue.",
        "guid": "2b06a1b3-8557-4032-a044-f80c382872f8",
        "h": null,
        "kind": "podcast_episode",
        "last_modified": "2024-12-10T14:00:43.948607Z",
        "original_article_url": "",
        "photo_author": "",
        "publication_date": "2024-12-10T14:00:00Z",
        "rankings": {
            "daily": null,
            "monthly": null,
            "weekly": null
        },
        "series_guid": "666a9c8d-9e5e-4bb7-b9f1-9fcc1418e4b7",
        "series_tags": [],
        "series_title": "Rock-uutiset",
        "source_type": "manual",
        "square_cover_url": null,
        "square_photo_author": null,
        "tags": [],
        "title": "Rock Uutiset 10.12."
      }
    ],
    "rankings": {
      "daily": 380,
      "weekly": 514,
      "monthly": 527
    },
    "cover_url": "https://data.richie.app/books-images/m/Nelonen/uploads/68e71fd81d_Cover_uploads_3d05c94bf6_RockUutiset_png_original.png"
  }
}

Schema of "data"

PropertyDescriptionValue
guidIdentifier of the series.UUID
last_modifiedLast time the series object or its episodes changed for any reason.String (a date).
rss_feed_urlOriginal RSS feed URL the series was sourced from.String (a URL), of source is RSS. Empty for others.
titleTitle of the series.String
authorAuthor of the series.String
descriptionPlain-text description of the series.String
html_descriptionHTML-formatted description of the series, if available.String or null
link"link" value from an RSS series.String
publication_dateInitial publication date for the latest episode.String or null
copyright"copyright" value from an RSS series.String
publisherName of the series' publisher.String
tagsTenant-specific values agreed with the tenant, for the series.Array of strings.
categoriesCategory IDs.Array of strings.
episodesEpisodes belonging to the series.Array of podcast episodes. See podcast_episode endpoint for details.
rankingsPopularity rankings for the series.Object
rankings.dailyDaily popularity for the series, if applicable. Lower number means more popular.Integer or null.
rankings.weeklyWeekly popularity for the series, if applicable. Lower number means more popular.Integer or null.
rankings.monthlyMonthly popularity for the series, if applicable. Lower number means more popular.Integer or null.
cover_urlCover URL for the series.An HTTPS URL.

GET /books/feeds/v3/podcast_categories.json

Get the list of all podcast categories.

Example response

{
  "data": {
    "f118a264-eb93-457b-aa21-2fac2376d575": {
      "cover_url": "https://data.richie.app/books-images/m/Nelonen/om/9985fe251b1fa73d228c575ba460cc2e0d165006-kansikuva.png?size=360",
      "guid": "f118a264-eb93-457b-aa21-2fac2376d575",
      "name": "Vapaa-aika ja harrastukset",
      "order": 37,
      "parent_category_guid": "fd882d2e-06b3-4f33-b714-df251c671575"
    },
    "fd882d2e-06b3-4f33-b714-df251c671575": {
      "cover_url": "",
      "guid": "fd882d2e-06b3-4f33-b714-df251c671575",
      "name": "Lifestyle",
      "order": 30,
      "parent_category_guid": null
    }
  }
}

Schema of data

"data" is an object with category identifiers as keys, with category objects as values.

PropertyDescriptionValue
[guid].guidIdentifier of the category.UUID
[guid].nameName of the category.String
[guid].orderNumber by which the categories should be sorted.Integer
[guid].cover_urlDecorative image for the category, if available.String, possibly empty.
[guid].parent_category_guidIdentifier of the category containing this category.String or null.

GET /books/feeds/v3/{tenant_name}/podcast_series_list.json

Get the list of all podcast series.

Example response

{
  "data": [
    {
      "guid": "666a9c8d-9e5e-4bb7-b9f1-9fcc1418e4b7",
      "last_modified": "2024-12-20T11:13:11.974746Z",
    }
  ]
}

Schema of data

"data" is an array.

PropertyDescriptionValue
[n].guidIdentifier of the series.UUID
[n].last_modifiedLast time the series object or its episodes changed for any reason.String (a date).

GET /audio_art/v1/{tenant_name}/all_articles.json

Get all currently available audio articles, suitable for synchronising with other systems.

Example response

{
  "data": [
    {
      "analytics_id": "2000010923770",
      "author": "Mikko Peltoniemi",
      "availability_periods": [
        {
          "end_date": "2099-12-31T23:59:59Z",
          "product": "suplaplus",
          "start_date": "2024-12-27T14:00:00Z",
          "type": "paid"
        }
      ],
      "categories": [
        "kulttuuri"
      ],
      "data_modified": "2024-12-27T14:05:04.857480Z",
      "extra": {
        "is_copy": true,
        "story_logo": "VS:n parhaat"
      },
      "guid": "9bdffb06-4fb0-5983-a488-0d4e9eb0bd64",
      "last_modified": "2024-12-27T14:00:00Z",
      "original_article_url": "https://www.valkeakoskensanomat.fi/elamanmeno/art-2000010923770.html?utm_source=supla&utm_medium=referral&utm_campaign=audio_articles",
      "photo_author": "Mikko Peltoniemi / Valkeakosken Sanomat",
      "photo_caption": "Hieman yllättäenkin tapahtunut paluu Valkeakoskelle on tarkoittanut muun muassa sitä, että Kimmo Virtasen tyttäret saavat usein kuulla, missä isä on lapsena ja nuorena mitäkin tehnyt.",
      "photo_url": "https://data.richie.app/images/v1/Nelonen/JN2sJlxo4Tjj5zCMayRKNpXlwKWGdKXdLDxxW7tlaNZNssxnrxQ_kjxVo8RgtfS_ghaw7DYgGWM9ByVDPoUvkbvMZ8BbKtelflokHgBOs3Q1JXjPsNY4",
      "publication_date": "2024-12-27T14:00:00Z",
      "rankings": {
        "daily": null,
        "monthly": null,
        "weekly": null
      },
      "source_tags": [
        "brand-vs",
        "brand:Valkeakosken Sanomat",
        "brand-icon:https://img.nm-ovp.nelonenmedia.fi/v1/novelist?src=/files/misc_images/2024-10/brand-vs.png"
      ],
      "square_photo_author": "Mikko Peltoniemi / Valkeakosken Sanomat",
      "square_photo_caption": "Hieman yllättäenkin tapahtunut paluu Valkeakoskelle on tarkoittanut muun muassa sitä, että Kimmo Virtasen tyttäret saavat usein kuulla, missä isä on lapsena ja nuorena mitäkin tehnyt.",
      "square_photo_url": "https://data.richie.app/images/v1/Nelonen/m9h5dd_V6ZJtffoBqIjKaoQ27gnKshFYDNaVCNG0v3H7UgYs4NNhD2hF_bmrPM4NY6VDtkPXRRr22rc6XEMFxAwkA6sdsNG8plZqnSzX2gagoHYSa80h",
      "text": "Loppuaan lähenevä vuosi 2024 on ollut Kimmo Virtaselle poikkeuksellinen. Sydänleikkausta ja synnyinkaupunkiin muuttoa seurasi uusi työ teatterinjohtajana. Kohta kotisohvilla katsotaan Virtasen kirjoittamaa Joulukalenteria. Valkeakosken Sanomat julkaisee joulun ja uudenvuoden aikaan vuoden parhaita juttujaan. Tämä juttu on julkaistu ensimmäisen kerran 24. marraskuuta 2024.",
      "title": "Paluumuuttaja Kimmo Virtasen uusi sydän sykkii Valkeakoskelle – joulukuussa nähtävää tv-klassikkoa hän kirjoitti vuoden, vaikka idea tyrmättiin tylysti"
    }
  ]
}

Schema of "data"

"data" is an array.

PropertyDescriptionValue
[n].guidIdentifier of the article.UUID
[n].authorAuthor of the article.String
[n].publication_dateOriginal publication date of the article.String (a date)
[n].last_modifiedDate of the last editorial modification to the article.String (a date)
[n].data_modifiedDate of the article was last modified for any reason. Covers technical and expected changes, which `"last_modified"` does not.String (a date)
[n].titleTitle of the article.String
[n].textText of the article.String
[n].photo_urlURL of the article's photo.String (an URL)
[n].photo_captionCaption of the article's photo.String
[n].photo_authorAuthor of the article's photo.String
[n].square_photo_urlURL of the article's photo, guaranteed square.String (an URL)
[n].square_photo_captionCaption of the article's photo, guaranteed square.String
[n].square_photo_authorAuthor of the article's photo, guaranteed square.String
[n].original_article_urlURL of the original version of the article.String (an URL)
[n].extraTenant-specific fields related to the article, to be agreed.Object
[n].availability_periodsTime frames during which the article is available in given products.Array of objects (availability period objects).
[n].availability_periods[m].productProduct slug.String or null.
[n].availability_periods[m].productType of the product (free or paid)."free" or "paid".
[n].availability_periods[m].productStart of episode's inclusion in the product.String (a date).
[n].availability_periods[m].end_dateEnd of episode's inclusion in the product.String (a date).
[n].analytics_idAn unprocessed identifier propagated from the source system, suitable for associating articles across systems.String
[n].source_tagsTenant-specific fields related to the source configuration, to be agreed.Array of strings
[n].rankingsPopularity rankings for the article.Object
[n].rankings.dailyDaily popularity for the article, if applicable. Lower number means more popular.Integer or null.
[n].rankings.weeklyWeekly popularity for the article, if applicable. Lower number means more popular.Integer or null.
[n].rankings.monthlyMonthly popularity for the article, if applicable. Lower number means more popular.Integer or null.
[n].categoriesSlugs of categories the article belongs to.Array of strings

GET /audio_art/v1/{tenant_name}/collections.json

Get currently available collections (categories) of articles.

Example response

{
  "data": [
    {
      "guid": "ae214c14-fe36-44e1-8580-3912e94e5aa4",
      "articles": [
        "e2bd232e-b371-503e-bd9a-4de89b9dc8b6",
        "8ba5ca10-d022-5272-936a-c3540386263c",
      ],
      "key": "ihmissuhteet",
      "display_name": "Ihmissuhteet"
    }
  ]
}

Schema of "data"

"data" is an array.

PropertyDescriptionValue
guidIdentifier of the collection.UUID
articlesIdentifiers of articles belonging to the collection.Array of UUIDs.
keySlug-like identifier of the collection.String
display_nameHuman readable name for the collection.String

GET /audio_art/v1/{tenant_name}/article_compat/{article_id}.json

Get an audio article as a podcast episode (a compatibility endpoint for existing players).

Example response

{
  "data": {
    "ad_tags": {},
    "analytics_data": {},
    "audio_duration": 0,
    "audio_length": 0,
    "audio_pkgs": {},
    "audio_sample": {
      "audio_duration": 0,
      "audio_length": 0,
      "audio_url": "https://data.richie.app/audiobooks/samples/Nelonen/3cbf1f32-83c7-4ffa-84a4-43f652d24b51/590aae_Supla_audioartikkelien_maksumuurin_audio.mp3"
    },
    "audio_url": "https://data.richie.app/audio_art_dist/Nelonen/audio_art/v1/audio/9bdffb06-4fb0-5983-a488-0d4e9eb0bd64.mp3",
    "author": "Mikko Peltoniemi",
    "availability_periods": [
      {
        "end_date": "2099-12-31T23:59:59Z",
        "product": "suplaplus",
        "start_date": "2024-12-27T14:00:00Z",
        "type": "paid"
      }
    ],
    "cover_url": "https://data.richie.app/images/v1/Nelonen/JN2sJlxo4Tjj5zCMayRKNpXlwKWGdKXdLDxxW7tlaNZNssxnrxQ_kjxVo8RgtfS_ghaw7DYgGWM9ByVDPoUvkbvMZ8BbKtelflokHgBOs3Q1JXjPsNY4",
    "description": "Loppuaan lähenevä vuosi 2024 on ollut Kimmo Virtaselle poikkeuksellinen. Sydänleikkausta ja synnyinkaupunkiin muuttoa seurasi uusi työ teatterinjohtajana. Kohta kotisohvilla katsotaan Virtasen kirjoittamaa Joulukalenteria. Valkeakosken Sanomat julkaisee joulun ja uudenvuoden aikaan vuoden parhaita juttujaan. Tämä juttu on julkaistu ensimmäisen kerran 24. marraskuuta 2024.",
    "guid": "9bdffb06-4fb0-5983-a488-0d4e9eb0bd64",
    "h": null,
    "kind": "audio_article",
    "last_modified": "2024-12-27T14:00:00Z",
    "original_article_url": "https://www.valkeakoskensanomat.fi/elamanmeno/art-2000010923770.html?utm_source=supla&utm_medium=referral&utm_campaign=audio_articles",
    "photo_author": "Mikko Peltoniemi / Valkeakosken Sanomat",
    "publication_date": "2024-12-27T14:00:00Z",
    "rankings": {
      "daily": null,
      "monthly": null,
      "weekly": null
    },
    "series_guid": "9bdffb06-4fb0-5983-a488-0d4e9eb0bd64",
    "series_tags": [
      "brand-vs",
      "brand:Valkeakosken Sanomat",
      "brand-icon:https://img.nm-ovp.nelonenmedia.fi/v1/novelist?src=/files/misc_images/2024-10/brand-vs.png"
    ],
    "series_title": "Mikko Peltoniemi",
    "source_type": "article",
    "square_cover_url": "https://data.richie.app/images/v1/Nelonen/m9h5dd_V6ZJtffoBqIjKaoQ27gnKshFYDNaVCNG0v3H7UgYs4NNhD2hF_bmrPM4NY6VDtkPXRRr22rc6XEMFxAwkA6sdsNG8plZqnSzX2gagoHYSa80h",
    "square_photo_author": "Mikko Peltoniemi / Valkeakosken Sanomat",
    "tags": [
      "joulukalenteri",
      "teatteri",
      "sydan--ja-verisuonitaudit",
      "joulu"
    ],
    "title": "Paluumuuttaja Kimmo Virtasen uusi sydän sykkii Valkeakoskelle – joulukuussa nähtävää tv-klassikkoa hän kirjoitti vuoden, vaikka idea tyrmättiin tylysti"
  }
}

Schema of "data" (a podcast episode)

"data" follows the schema for a podcast episode, with some podcast-specific fields left empty.

PropertyDescriptionValue
kindKind (type) of the resource."audio_article"
source_typeOrigin of the "episode"."article"
guidIdentifier of the article.UUID
series_titleArticle author, duplicated. Set for compatibility.String
series_guidArticle identifier, duplicated. Set for compatibility.UUID
authorArticle author.String
original_article_urlOriginal article URL.String
titleArticle title.String
descriptionArticle text.String
publication_dateArticle's first publication date.String (a date)
last_modifiedLast time the metadata was updated.String (a date).
cover_urlURL for a cover picture.String (an HTTPS URL).
photo_authorAuthor of the related photo.String
square_cover_urlURL for a cover picture, guaranteed to be square.String (an HTTPS URL) or null.
square_photo_authorURL for a cover picture, guaranteed to be square.String or null.
audio_urlPlayback URL for the main audio.String (an HTTPS URL).
audio_durationDuration of audio in seconds. 0 and null mean duration is unknown.Integer (incl. 0) or null.
audio_lengthContent length of audio file, in bytes. 0 means unknown length.Integer (incl. 0).
audio_sampleDetails of a free sample version for audio. Not available for all articles.Object or null.
audio_sample.audio_urlPlayback URL for the sample version.String (an HTTPS URL) if audio_sample is an object.
audio_sample.audio_durationDuration of audio in seconds. 0 and null mean duration is unknown.Integer (incl. 0) or null if audio_sample is an object..
audio_sample.audio_lengthContent length of audio file, in bytes. 0 means unknown length.Integer (incl. 0) if audio_sample is an object..
audio_pkgsRichie-managed alternative format audio packages. Details agreed with integrators.Object, possibly empty.
availability_periodsTime frames during which the episode is available in given products.Array of objects (availability period objects).
availability_periods[n].productProduct slug.String or null.
availability_periods[n].productType of the product (free or paid)."free" or "paid".
availability_periods[n].productStart of episode's inclusion in the product.String (a date).
availability_periods[n].end_dateEnd of episode's inclusion in the product.String (a date).
rankingsPopularity rankings for the article.Object
rankings.dailyDaily popularity for the article, if applicable. Lower number means more popular.Integer or null.
rankings.weeklyWeekly popularity for the article, if applicable. Lower number means more popular.Integer or null.
rankings.monthlyMonthly popularity for the article, if applicable. Lower number means more popular.Integer or null.
series_tagsTenant-specific values agreed with the tenant, for the series article belongs to.Array of strings.
tagsTenant-specific values agreed with the tenant, for the article.Array of strings.
analytics_dataTenant-specific data carried for analytics purposes. Actual fields agreed with the tenant.Object or null.
ad_tagsTenant-specific data carried for ad purposes. Actual fields agreed with the tenant.Object or null.
hInternal hash code over the payload, not always set.String or null.
Previous
Push Credentials
Next
App Support Policy