ordbog.gyldendal.dk

Nedenfor følger en beskrivelse af API’et til Gyldendals Røde Ordbøger. API’et er lavet som en HTTP-webservice som kaldes med query-string parametre. Adressen API’et skal spørge på er http://ordbog.gyldendal.dk.

Query-syntaks

http://ordbog.alpha-solutions.dk/ordbog/layouts/apisearch.aspx?q=ugle&lcode=DAEN

Bemærk: Syntaksen i url’en ligger fast, men den indledende sti bliver en anden. Den angivet er til vores test-site.

I det med grønt markerede indsættes søgeordet efter strengen ”q=”. Husk encoding af specialtegn (inkl. æøåÆØÅ). Kaldsparametre skal være korrekt UTF-8 encodede.

Dette kan f.eks. gøres vha. encodeURIComponent functionen indbygget i Javascript.

I det med lilla markerede angives sprogretningen, tilladte værdier er:

XML-struktur for svar fra API’et

Grammatikken for API'ets svar findes i form af et W3C XML-schema i filen: dictionary-answer.xsd.

Her gengives grammatikken grafisk:

Forklaring

En forespørgsel returnerer altid et <answer>-element. Den valgte oversættelsesretning holdes der styr på i attributterne @source-language og @target-language. <answer>-elementet indeholder først søgeordet i elementet <search-string>, derefter enten 1 eller flere stk. <dictionary-answer> eller elementet <message>. API’et afleverer et <message>-element, når der ikke afleveres en oversættelse.

Tilladte værdier for attributterne @source-language og @target-language er:

Eksempel 1

Herunder ses det svar man får fra API’et, når man slår ordet ”ugle” op i Dansk-Engelsk:

<answer source-language="dan" target-language="eng">

<search-string>ugle</search-string>

<dictionary-answer>

<id>

<word>ugle</word>

<pos>sb.</pos>

<word-description>fugl; insekt</word-description>

</id>

<result>

<headword>ugle</headword>

<sense-description>uønsket tilskuer, fx ved kortspil, uformelt, am.</sense-description>

<translation>kibitzer</translation>

</result>

<result>

<headword>ugle</headword>

<sense-description>zo.</sense-description>

<translation>owl</translation>

</result>

<result>

<headword>ugle</headword>

<sense-description>zo., fugl: Strigidae</sense-description>

<translation>owl</translation>

</result>

<result>

<headword>ugle</headword>

<sense-description>zo., natsværmer: Noctuidae</sense-description>

<translation>owlet moth</translation>

</result>

<gyldendal-URL>http://ordbog.gyldendal.dk/?aq=ugle&amp;lcode=DAEN</gyldendal-URL>

</dictionary-answer>

<dictionary-answer>

<id>

<word>ugle</word>

<pos>vb.</pos>

<word-description>filtre</word-description>

</id>

<result>

<headword>ugle</headword>

<sense-description>bringe i uorden</sense-description>

<translation>rumple</translation>

</result>

<gyldendal-URL>http://ordbog.gyldendal.dk/?aq=ugle&amp;lcode=DAEN</gyldendal-URL>

</dictionary-answer>

</answer>

<dictionary-answer>

Hvert <dictionary-answer>-element svarer til et unikt genkendt opslagsord. Dette opslagsord beskrives i elementet <id>.

Desuden indeholder hvert <dictionary-answer> ét <result>-element for hver oversættelse der kan findes i de tilgængelige ordbøger.

<id>

Elementet <id> der indeholder ordets stavning i elementet <word>, ordets ordklasse i elementet <pos> (=part of speech) samt evt. et element <word-description>, der kort beskriver det genkendte ord.

<result>

Selve <result>-elementet indeholder elementerne <headword> med et opslagsord (evt. i en bøjet form) og <translation> med ordets oversættelse. Endelig kan <result>-elementet også indeholde et element <sense-description>, der med en kort tekst beskriver hvilken betydning af opslagsordet, der oversættes. Bemærk at <headword> og <translation> er obligatoriske i et <result>-element mens <sense-description> er valgfrit.

I eksemplet ovenfor oversættes hele tre betydninger af substantivet ugle, nemlig fuglen, der kaldes ”owl” på engelsk, insektet, der hedder ”owlet moth” samt en uønsket tilskuer der kan oversættes til ”kibitzer”.

Hvis et <result> har sat @additional-info-attributte til ”true” betyder det at der er mere information at hente på hjemmesiden (fx i form af brugseksempler). Dette er en opfordring til brugerne af API'et om at linke til Gyldendals hjemmeside som findes i <gyldendal-url>.

Eksempel 2

Når der ikke kan returneres oversættelser fra de tilgængelige ordbøger, returnerer API’et elementet <message> i stedet for ét eller flere <dictionary-answer>-elementer:

<answer source-language="dan" target-language="eng">

<search-string>pransesse</search-string>

<dictionary-answer/>

<message>no entries found</message>

</answer>

Elementet <message> kan indeholde flg. værdier:

Log in og adgangskontrol

Online-ordbøgerne sælges som abonnements-service og er derfor beskyttet af en adgangskontrol. Adgangskontrollen benytter en af to metoder til adgangskontrol:

det tillades brugere med registreret/godkendt IP-adresse at foretage søgninger

det tillades brugere med godkendt brugernavn/password at foretage søgninger.

API’et er lavet, så det kan benytte samme metodik. Metoden til søgning ved hjælp af b/p er som vist I url’en herunder:

http://ordbog.gyldendal.dk/ordbog/layouts/apisearch.aspx?q=slem&lcode=DAEN&login=<brugernavn>&password=<password>

Søger man fra registreret IP-adresse, foretager servicen automatisk godkendelse.

Bemærk i øvrigt, at sitet og API’et accepterer tre gratis opslag pr. døgn, uden man er IP- eller b/p-valideret.