Gweld cod am API S4C Clic

Mae S4C Clic yn defnyddio API ac mae modd gwneud ceisiadau a derbyn data rhaglenni mewn fformat JSON.

== Pwysig ==

Mae'r API yn llwytho yn y porwr gwe bob tro mae unrhyw un yn ymweld â Clic.
 
Nid yw'r API yn cael ei hysbysebu o gwbl fel gwasanaeth cyhoeddus.

Y ffordd fwyaf parchus i'w ddefnyddio yw i drio defnyddio fe 'fel porwr gwe'. Mewn theori mae terfyn ar y nifer o geisiadau rydych chi'n gallu gwneud o fewn amser.

Does dim dogfennaeth swyddogol. Wrth gwrs mae'r API yn gallu newid yn y dyfodol heb rybudd.

== Categorïau ==

Dyma restr o gategorïau (neu 'genres') a'u rhifau cod.

<code><nowiki>https://www.s4c.cymru/df/category_list_feed?lang=c</nowiki></code>

Dyw e ddim yn aml ond mae rhai categorïau fel Nadolig sydd yn mynd yn fwy neu lai pwysig.

Cyw yw'r categori am yr holl raglenni plant ifanc.

== Dyddiad o raglennu ==

Mae cyfeiriad o'r fformat:

<code><nowiki>https://www.s4c.cymru/df/listings_for_date?lang=c&date=BBBB-MM-DD</nowiki></code>

yn dychwelyd rhaglenni am ddyddiad.

e.e. https://www.s4c.cymru/df/listings_for_date?lang=c&date=2021-12-07

Mae llawer o ddata wrth y cais yma yn ei hun.

=== Allbwn - enghraifft ===

Nodwch fy mod wedi torri mas llawer o raglenni isod i leihau.

<code>
{
  "listings_for_date": [
    {
      "programme_title": "Heno",
      "series_title": "Heno",
      "short_billing": "Heno, byddwn ni'n ymweld ag Ysgol Plascrug sydd wedi recordio cân arbennig i godi arian at elusennau lleol. Byddwn hefyd yn cael cwmni Elen Rhys, Comisiynydd Adloniant S4C, i sôn am arlwy Nadolig S4C, ac fe fydd cyfle i gymryd rhan yn ein cystadleuaeth Cracyr Dolig.",
      "duration": "00:30:00",
      "thumbnail_url": "Heno_2016S4C_002.jpg",
      "date_broadcast": "2021-12-07 19:00:00",
      "end_dt": "2021-12-07 19:30:00",
      "id": "822416263",
      "episode_num": "173",
      "available": "programme_id=822416263",
      "container": "N",
      "contained": "N",
      "b888": "Y",
      "b889": "N",
      "b_audio_described": "N",
      "b_visually_signed": "N"
    },
    {
      "programme_title": "Pobol y Cwm",
      "series_title": "Pobol y Cwm",
      "short_billing": "Daw'r heddlu gwrth-derfysgaeth i Gwmderi i ymweld ag un o'r pentrefwyr sy'n peri gofid iddynt. Draw yn y Winllan, mae Gaynor yn agor ei chalon gyda Sion. ",
      "duration": "00:25:00",
      "thumbnail_url": "pobol_y_cwm_2021_12_07_P126.jpg",
      "date_broadcast": "2021-12-07 20:00:00",
      "end_dt": "2021-12-07 20:25:00",
      "id": "820711181",
      "episode_num": "126",
      "available": "programme_id=820711181",
      "container": "N",
      "contained": "N",
      "b888": "Y",
      "b889": "Y",
      "b_audio_described": "Y",
      "b_visually_signed": "N"
    },
    {
      "programme_title": "Cefn Gwlad",
      "series_title": "Cefn Gwlad",
      "short_billing": "Ifan Jones Evans sy'n ymweld â busnes teiars teuluol a'i bencadlys yng Ngherrigydrudion, sy'n cynnig gwasanaeth i bobl cefngwlad ar hyd a lled Gogledd Orllewin Cymru. Hefyd Ioan Doyle sy'n cwrdd a'r gwr o Edern sy'n dal tyrchod daear, Meleri Garn Fach sy'n cwrdd a bwtsiar Llanrug, a beth yw apel cefngwlad i'r gantores Lowri Evans, Trefdraeth'",
      "duration": "01:00:00",
      "thumbnail_url": "Cefn_Gwlad_2021-22S4C_P7_Teulu_Teiars_017.jpg",
      "date_broadcast": "2021-12-07 21:00:00",
      "end_dt": "2021-12-07 22:00:00",
      "id": "826187255",
      "episode_num": "7",
      "available": "programme_id=826187255",
      "container": "N",
      "contained": "N",
      "b888": "Y",
      "b889": "Y",
      "b_audio_described": "Y",
      "b_visually_signed": "N"
    },
  ]
}
</code>

== Manylion am raglen unigol ==

Yn gyntaf nodwch fod modd llwytho tudalen y rhaglen mewn porwr gyda:
 
<code><nowiki>https://www.s4c.cymru/clic/programme/RHOWCH_ID_Y_RHAGLEN</nowiki></code>

Mae hwn

<code><nowiki>https://www.s4c.cymru/df/full_prog_details?lang=c&programme_id=RHOWCH_ID_Y_RHAGLEN_YMA&show_prog_in_series=Y</nowiki></code>

yn dychwelyd data ar gyfer tudalen rhaglen unigol.

e.e.
https://www.s4c.cymru/df/full_prog_details?lang=c&programme_id=537089908&show_prog_in_series=Y

Mae hyn yn cynnwys:
* days_to_expire
* subtitle_e - ffeil is-deitlau Saesneg fel XML
* programme_title
* series_title (weithiau does dim gwahaniaeth rhwng programme_title a series_title)
* full_billing - disgrifiad llawn
* last_tx - dyddiad
* clic_aired - dyddiad
* id - ID unigryw y rhaglen
* unsuitable - rhywbeth i'w wneud â chynnwys
* short_billing - disgrifiad byr
* thumbnail_url - enw y JPG
* duration - mewn munudau
* series_id
* subtitle_c - ffeil is-deitlau Cymraeg fel XML
* genre_ids - un neu fwy o IDs categorïau gyda comas i'w gwahanu
* b_visually_signed 
* other_version_available - ?
* audio_description - boolean
* rhaglenni yn yr un gyfres - 

=== Allbwn - enghraifft ===

<code>
{
  "full_prog_details": [
    {
      "days_to_expire": "0",
      "subtitle_e": "E_A814666978.xml",
      "programme_title": "Costa Rica",
      "series_title": "Her Yr Hinsawdd",
      "crid": "crid://s4c.co.uk/yvv-537089908",
      "full_billing": "Byddwn yn dilyn yr Athro Siwan Davies i wlad drofannol Costa Rica lle mae'r bywyd gwyllt anhygoel a'r golygfeydd hudolus o dan fygythiad enfawr o ganlyniad i newid hinsawdd a degawdau o ddatgoedwigo.",
      "last_tx": "9 Tachwedd 2021",
      "clic_aired": "3 Tachwedd 2021",
      "fav_id": "537089847",
      "id": "537089908",
      "mpg": "her_yr_hinsawdd__costa_rica_audio_descr_rcd89r_00308ed4e2.mp4",
      "unsuitable": "0",
      "short_billing": "Yr Athro Siwan Davies sy'n esbonio mwy am oblygiadau'r newid hinsawdd presennol. ",
      "thumbnail_url": "Her_yr_Hinsawdd_2017_P2_Costa_Rica_1403.jpg",
      "duration": "23",
      "series_id": "537089862",
      "subtitle_c": "C_A814666978.xml",
      "vs": "0",
      "imi": "imi://s4c.co.uk/yvo-n-537089908",
      "genre_ids": "1",
      "other_version_available": true,
      "audio_description": true
    }
  ],
  "other_progs_in_genres": [
    {
      "count": "106",
      "days_to_expire": "149",
      "programme_title": null,
      "series_title": "Prynhawn Da",
      "short_billing": "Heddiw, mi fydd Huw yn agor ei gwpwrdd dillad ac mi fydd ein harbenigwr gwin, Dylan Rowlands, yn ymuno â ni. Bydd hefyd cyfle i gymryd rhan yn ein cystadleuaeth Cracyr Dolig.",
      "thumbnail_url": "Prynhawn_Da_Cyfres_2017_Hydref.jpg",
      "duration": "42",
      "series_id": "520950923",
      "full_billing": "Heddiw, mi fydd Huw yn agor ei gwpwrdd dillad ac mi fydd ein harbenigwr gwin, Dylan Rowlands, yn ymuno â ni. Bydd hefyd cyfle i gymryd rhan yn ein cystadleuaeth Cracyr Dolig.",
      "clic_aired": "7 Rhagfyr 2021",
      "fav_id": "822450302",
      "id": "822454396"
    },
    {
      "count": "9",
      "days_to_expire": "78",
      "programme_title": null,
      "series_title": "Wil ac Aeron: Taith yr Alban",
      "short_billing": "Cyfres yn dilyn y ffermwyr ifanc Wil Hendreseifion ac Aeron Pughe ar daith i'r Alban. ",
      "thumbnail_url": "Wil_ac_Aeron_2016S4C_Taith_Yr_Alban_P5_163435.jpg",
      "duration": "24",
      "series_id": "534116591",
      "full_billing": "Mae camperfan y ddau ffermwr, Wil Hendreseifion ac Aeron Pughe, wedi llwyddo i'w cludo i ben y daith o dros 1,500 o filltiroedd o amgylch yr Alban.  Yn y bennod olaf maen nhw'n treulio amser yn dod i adnabod ffordd o fyw'r Crofters ar Ynys Uist yn yr Hebrides.  Er bod rhai ar yr ynys yn glynu at dechnegau traddodiadol o ffermio, mae eraill yn gweld bod rhaid addasu os am oroesi.  Ar ddiwedd y daith fythgofiadwy mae'r ddau yn profi uchafbwynt eu siwrnai ac yn gwireddu breuddwyd.",
      "clic_aired": "12 Hydref 2021",
      "fav_id": "534116664",
      "id": "534116779"
    },
    {
      "count": "2",
      "days_to_expire": "26",
      "programme_title": "Byw yn y Wlad",
      "series_title": "Cymru ar Ffilm",
      "short_billing": "Beti George sy'n rhannu rhai o'r goreuon o archif BBC Cymru - ffilmiau sy'n gofnod o ddiwedd yr hen ffordd Gymreig o fyw a geni Cymru newydd.",
      "thumbnail_url": "Cymru_ar_Ffilm_2015.jpg",
      "duration": "23",
      "series_id": "796019604",
      "full_billing": "Beti George sy'n rhannu rhai o'r goreuon o archif BBC Cymru - ffilmiau sy'n gofnod o ddiwedd yr hen ffordd Gymreig o fyw a geni Cymru newydd. Am ganrifoedd, ffermio oedd asgwrn cefn y Gymru wledig ac edrychai pobl i'w milltir sgwâr am gynhaliaeth. Ond yn gyflym iawn, diolch i'r busnes gwyliau a hamdden, cafodd rhai o'n hardaloedd prydferthaf eu gweddnewid.    ",
      "clic_aired": "3 Rhagfyr 2021",
      "fav_id": "524301067",
      "id": "524301306"
    }
  ],
  "other_progs_in_series": [
    {
      "days_to_expire": "9",
      "subtitle_e": "E_A814676258.xml",
      "programme_title": "Cymru",
      "series_title": "Her Yr Hinsawdd",
      "crid": "crid://s4c.co.uk/yvv-537090036",
      "full_billing": "Yn y bennod olaf, bydd Siwan yn ymweld ag arbenigwyr ar draws Cymru i ddysgu mwy am yr hyn sy'n cael ei wneud i sicrhau dyfodol cynaliadwy a llewyrchus. Bydd Siwan yn ymweld â phrosiect cymunedol Ynni Padarn i ddysgu am ffyrdd o gael egni glân ar gyfer y dyfodol. Bydd Yr Athro Rhys Jones yn esbonio pam mae'n rhaid newid agwedd pobl tuag at newid hinsawdd a bydd yr Athro Gareth Wyn Jones yn trafod yr hyn y gall pobl gyffredin ei wneud i geisio lleihau lefelau carbon deuocsid yn yr atmosffer.",
      "last_tx": "12 Tachwedd 2021",
      "clic_aired": "12 Tachwedd 2021",
      "fav_id": "537089847",
      "id": "537090036",
      "count": "10",
      "mpg": "her_yr_hinsawdd__cymru_audio_descriptio_r39c3r_00308ef922.mp4",
      "unsuitable": "0",
      "short_billing": "Yr Athro Siwan Davies sy'n esbonio mwy am oblygiadau'r newid hinsawdd presennol. ",
      "thumbnail_url": "Her_yr_Hinsawdd2017_P6_Cymru_002.jpg",
      "duration": "23",
      "series_id": "537089862",
      "subtitle_c": "C_A814676258.xml",
      "vs": "0",
      "imi": "imi://s4c.co.uk/yvo-n-537090036"
    },
    {
      "days_to_expire": "7",
      "subtitle_e": "E_A814676486.xml",
      "programme_title": "Norwy",
      "series_title": "Her Yr Hinsawdd",
      "crid": "crid://s4c.co.uk/yvv-537090004",
      "full_billing": "Bydd yr Athro Siwan Davies yn dechrau ei thaith yn Longyearbyen, y ddinas fwyaf gogleddol yn y byd. Bydd Siwan yn cyfarfod gwyddonwyr o'r Norwegian Polar Institute a theuluoedd sydd wedi colli eu cartrefi a'u cariadon yn y cwympiadau eira dychrynllyd sy'n digwydd yn amlach y dyddiau hyn ar ynysfor Svalbard. Bydd Siwan hefyd yn teithio i ddinas Tromso yng ngogledd tir mawr Norwy i gwrdd â ffermwyr ceirw Sami sy'n gorfod newid eu ffordd draddodiadol o ffermio o ganlyniad i dywydd twym, annhymhorol",
      "last_tx": "10 Tachwedd 2021",
      "clic_aired": "10 Tachwedd 2021",
      "fav_id": "537089847",
      "id": "537090004",
      "count": "10",
      "mpg": "her_yr_hinsawdd__norwy_audio_descriptio_r0f96r_00308efa06.mp4",
      "unsuitable": "0",
      "short_billing": "Yr Athro Siwan Davies sy'n esbonio mwy am oblygiadau'r newid hinsawdd presennol. ",
      "thumbnail_url": "Her_yr_Hinsawdd2017_P5_Norwy_6339.jpg",
      "duration": "23",
      "series_id": "537089862",
      "subtitle_c": "C_A814676486.xml",
      "vs": "0",
      "imi": "imi://s4c.co.uk/yvo-n-537090004"
    },
    {
      "days_to_expire": "5",
      "subtitle_e": "E_A814672514.xml",
      "programme_title": "California #2 ",
      "series_title": "Her Yr Hinsawdd",
      "crid": "crid://s4c.co.uk/yvv-537089972",
      "full_billing": "Y tro hwn, mae'r Athro Siwan Davies yn parhau â'i thaith o amgylch Califfornia. Bydd yn cyfarfod teuluoedd heb dd¿r yn eu tai o ganlyniad i'r sychder, ac yn ymweld â nifer o brosiectau arloesol sydd yn ceisio ymdopi â newid hinsawdd.",
      "last_tx": "23 Tachwedd 2021",
      "clic_aired": "8 Tachwedd 2021",
      "fav_id": "537089847",
      "id": "537089972",
      "count": "10",
      "mpg": "her_yr_hinsawdd__california_2__audio_d_r62d0r_00308eea82.mp4",
      "unsuitable": "0",
      "short_billing": "Yr Athro Siwan Davies sy'n esbonio mwy am oblygiadau'r newid hinsawdd presennol. ",
      "thumbnail_url": "Her_yr_Hinsawdd_P4_004.jpg",
      "duration": "23",
      "series_id": "537089862",
      "subtitle_c": "C_A814672514.xml",
      "vs": "0",
      "imi": "imi://s4c.co.uk/yvo-n-537089972"
    },
    {
      "days_to_expire": "2",
      "subtitle_e": "E_A814711868.xml",
      "programme_title": "California #1",
      "series_title": "Her Yr Hinsawdd",
      "crid": "crid://s4c.co.uk/yvv-537089940",
      "full_billing": "Mae'r Athro Siwan Davies yn teithio i Galiffornia, un o daleithiau mwyaf cyfoethog yr Unol Daleithiau i ymweld â Jet Propulsion Laboratory NASA i ddysgu mwy am eu prosiectau monitro hinsawdd. Un o effeithiau mwyaf gweledol newid hinsawdd yng Nghaliffornia yw'r cynnydd enfawr yn y nifer o danau gwyllt a welwyd ar draws y dalaith. Bydd Siwan yn ymweld â dwy fenyw sydd wedi colli popeth yn y tanau yn cynnwys eu tai ac eiddo, ac yn achos Donna Fink, ei chariad.",
      "last_tx": "16 Tachwedd 2021",
      "clic_aired": "5 Tachwedd 2021",
      "fav_id": "537089847",
      "id": "537089940",
      "count": "10",
      "mpg": "her_yr_hinsawdd__california_1_audio_de_r2c16r_00308f843c.mp4",
      "unsuitable": "0",
      "short_billing": "Yr Athro Siwan Davies sy'n esbonio mwy am oblygiadau'r newid hinsawdd presennol. ",
      "thumbnail_url": "Her_yr_Hinsawdd_2017_P3_California_7995.jpg",
      "duration": "23",
      "series_id": "537089862",
      "subtitle_c": "C_A814711868.xml",
      "vs": "0",
      "imi": "imi://s4c.co.uk/yvo-n-537089940"
    },
    {
      "days_to_expire": "0",
      "subtitle_e": "E_A814666978.xml",
      "programme_title": "Costa Rica",
      "series_title": "Her Yr Hinsawdd",
      "crid": "crid://s4c.co.uk/yvv-537089908",
      "full_billing": "Byddwn yn dilyn yr Athro Siwan Davies i wlad drofannol Costa Rica lle mae'r bywyd gwyllt anhygoel a'r golygfeydd hudolus o dan fygythiad enfawr o ganlyniad i newid hinsawdd a degawdau o ddatgoedwigo.",
      "last_tx": "9 Tachwedd 2021",
      "clic_aired": "3 Tachwedd 2021",
      "fav_id": "537089847",
      "id": "537089908",
      "count": "10",
      "mpg": "her_yr_hinsawdd__costa_rica_audio_descr_rcd89r_00308ed4e2.mp4",
      "unsuitable": "0",
      "short_billing": "Yr Athro Siwan Davies sy'n esbonio mwy am oblygiadau'r newid hinsawdd presennol. ",
      "thumbnail_url": "Her_yr_Hinsawdd_2017_P2_Costa_Rica_1403.jpg",
      "duration": "23",
      "series_id": "537089862",
      "subtitle_c": "C_A814666978.xml",
      "vs": "0",
      "imi": "imi://s4c.co.uk/yvo-n-537089908"
    }
  ]
}
</code>

== Iaith y data ==

Rhowch <code>lang=e</code> yn lle <code>lang=c</code> yn y cyfeiriadau uchod i dderbyn cynnwys/disgrifiadau/ayyb yn Saesneg.

== Heriau/problemau/nodiadau eraill ==

* Peidiwch â ddisgwyl ymateb gall os nad oes cynnwys ar gael neu os nad yw'r rhaglen ar gael. (Mae'r wefan ei hun yn dangos neges wall generig 'Mae'n ddrwg gennym! Roedd gwall wrth lwytho'r dudalen' yn hytrach na 'mae'r rhaglen wedi dod i ben, dyma rai eraill yn yr un gyfres...' ayyb).
* Mewn disgrifiadau mae'r symbol ¿ yn ymddangos yn lle ŵ a rhai collnodau. Mae hyn i weld y byg yn y system dw i'n meddwl?
* Mae hyd y rhaglen wrth full_prog_details (duration) weithiau'n wahanol i'r maes o'r un enw wrth listings_for_date. Dolenni Cyw yn enghraifft - segues yn unig o ddarllediad 2-awr. Mae full_prog_details yn cydymffurfio gyda hyd y rhaglen ar Clic yn amlach dw i'n meddwl.
* Nid oes ffrwd RSS/Atom o raglenni fel yr oedd yn yr hen fersiwn o'r wefan.
* Diolch i S4C a'r holl gynhyrchwyr am y rhaglenni, ac am ddarparu API mor ddiddorol!

== Enghreifftiau ==

* Mae'r bot awtomatig Twitter [https://twitter.com/offclic Clic Off] yn defnyddio'r API.
* [https://github.com/carlmorris/tracio-s4c-clic-ffeithiol-celf Crafwr git] arbrofol am raglenni ffeithiol a chelyddydau.

[[Categori:API Cymraeg]]
[[Categori:API Cymru]]