¿Qué vamos a cocinar?

Al final del tutorial, serás capaz de construir un diccionario de español en php como este usando las APIs de Apicultur.

Onomateca

El diccionario consta de una caja de búsqueda y un botón. Al consultar, obtenemos:

  • la palabra buscada destacada en la zona superior
  • en la columna central se muestran las definiciones. Cuando la hay, la primera definición que aparece es una definición simple de un diccionario básico (aparece con la letra un poco más destacada). A continuación, se listan las definiciones generales.
  • en la columna lateral izquierda aparece la info fonética (transcripción, silabeo, sílaba tónica, número de sílabas, tipo de palabra según acentuación), la categoría gramatical junto a su lema, la familia morfológica (formas flexionadas) y palabras con las que rima.
  • en la columna lateral derecha se muestra el nivel de frecuencia de la palabra, el nivel de dificultad según los niveles ABC del MCERL y una lista de palabras semánticamente relacionadas.

Ingredientes:

  • Acceso a un sitio web para subir la página que permita ejecutar php

Pasos a seguir

Registro en Apicultur y suscripción a las APIs

Lo primero que necesitamos es crearnos una cuenta en APIcultur. Apicultur es una plataforma de APIs donde puedes encontrar diversos servicios lingüísticos, como APIs de definiciones, análisis morfológico, transcripción fonética, información léxica y mucho más. Las APIs de Apicultur serán las que utilizaremos como ingredientes para confeccionar nuestro diccionario.

1. Para poder usar las APIs de APIcultur debes registrarte rellenando el formulario con tus datos. Cuando te hayas registrado, puedes entrar en APIcultur desde Login.

2. Una vez registrados y logueados, vamos a crear una nueva aplicación. Las aplicaciones sirven para agrupar y gestionar tus sucripciones a las APIs de Apicultur. Entra en la pestaña My Subscriptions del menú superior y haz click en New Application. Escoge el nombre que quieras (MiDiccionario, por ejemplo) y pulsa en Add. Ya tienes tu aplicación creada. Ahora sólo tendremos que escoger qué APIs queremos utilizar (es decir, qué funciones lingüísticas queremos añadir a nuestro diccionario) y suscribirnos a ellas.

3. Vamos a seleccionar las funciones que queremos incorporar a nuestro diccionario. Nosotros hemos escogido las siguientes APIs para nuestro diccionario:

Para poder utilizar una API necesitaremos conocer la URL de la API, saber qué parámetros debemos pasarle a la API, qué información nos va a devolver y qué formato tendrá el JSON devuelto. En el perfil de cada API de Apicultur tenemos toda esta información; la necesitaremos durante la programación del diccionario en php.

Para poder utilizar estas APIs, tenemos que suscribirnos a cada una ellas: estando logueados, entramos en la página principal de cada una de estas APIs, seleccionamos en el desplegable la aplicación que creamos (MiDiccionario) y presionamos Subscribe.

Debemos hacer esto con cada una de las APIs que vayamos a utilizar en nuestro diccionario. Nuestra propuesta utiliza las APIs del listado anterior, pero podéis cambiarlas o añadir otras: no tenéis más que navegar por Apicultur y suscribiros a las APIs que os interesen.

SinonimosPorPalabra

NuevaAplicacion

4. Una vez ya suscritos a las APIs que queremos usar, necesitamos obtener la clave o API key. La clave o API key es el código alfanumérico que nos identifica y que nos autorizará para llamar a las APIs. Para conseguirlo, solo tenemos que entrar en My Subscriptions y desplegar la aplicación MiDiccionario. Veremos que aparecen listadas todas las APIs a las que nos hayamos suscrito. Presionamos en Generate Keys y saldrán tres campos con tres claves alfanuméricas. La clave que usaremos es el código alfanumérico que aparece en el campo Access Token. La clave es común para todas las APIs suscritas bajo una misma aplicación. Es decir, hay un Access Token por aplicación, de tal manera que todas las APIs bajo la aplicación MiDiccionario tendrán la misma clave.

Mantén abierta la pestaña con el API key, ya que lo necesitaremos más adelante, cuando estemos escribiendo el código.

GenerarKey

Programación

Ya tenemos todos los ingredientes necesarios: tenemos nuestra cuenta en Apicultur, estamos suscritos a las APIs que nos interesan y hemos generado la clave o API key que nos identifica. Ya solo nos queda cocinarlos, es decir, escribir el código en php de nuestro diccionario.

El código fuente del diccionario está disponible en Github. También puedes descarlo desde este enlace. Una vez tengas el código, ábrelo con un editor como Notepad++. Puedes ir mirándolo según avancemos en el tutorial, para seguir la explicación mejor. Además, el código contiene comentarios que explican las distintas partes y funciones (texto en verde). Siéntete libre para copiar y pegar el código y editarlo a voluntad.

Como puedes ver, el código tiene tres partes: el html, el css y el script de php. El html contiene la estructura de la web, el css personaliza el diseño (fuentes tipográficas, colores, tamaños, etc) y el php que es el que contiene las tripas del diccionario y las llamadas a las APIs. Para el html y el css nos hemos inspirado en esta plantilla, ya que la estructura en tres columnas nos parecía la más funcional para un diccionario. Puedes utilizar la misma plantilla, reutilizar nuestra código directamente o escoger alguna de las muchas plantillas gratuitas disponibles en Internet.

Vamos a echarle un vistazo superficial al código para familiarizarnos con él. En la parte inicial aparece el html con la cabecera y el título de la web. Más abajo está el css que contiene el diseño (tipos de letras, colores, tamaños, etc; luego volveremos sobre ello). El meollo de la cuestión está en el script en php, que empieza en la línea 182 donde aparece

[php autolinks=”false” gutter=”true” collapse=”false” firstline=”4″ highlight=”true” light=”true” smarttabs=”true” tabsize=”4″ toolbar=”true”]
<?php
[/php]

y termina en la línea 977 con:

[php autolinks=”false” gutter=”true” collapse=”false” firstline=”4″ highlight=”true” light=”true” smarttabs=”true” tabsize=”4″ toolbar=”true”]
?>
[/php]

El código que viene a continuación de la línea 977 vuelve a ser html. Si te fijas, el código html que aparece en este punto es el formulario de búsqueda, con su caja para introducir la palabra que queramos buscar y un botón. La orden que contiene este código es que al hacer click en el botón, se ejectuará el script en php. Por último tenemos el footer, el pie de página. Esto es, a vista de pájaro, el contenido del archivo.

Volvamos a la línea 182, donde empieza el php, que es el meollo de la cuestión. En el php podemos distinguir tres partes:

  • Recogida del parámetro, es decir, recogemos la palabra que el usuario ha introducido en la caja de búsqueda. Líneas 190-194
  • Recorrido de la palabra en cuestión por las distintas funciones lingüísticas de nuestro diccionario, mostrando en la web la información obtenida (definiciones, transcripción, frecuencia, etc). Líneas 197-567
  • Funciones lingüsticas de php que llaman a las APIs de Apicultur. En esta parte del código, tenemos las funciones que llevan a cabo las funciones lingüísticas, llamando a las APIs a las que nos hemos suscrito. Será en este punto donde tendremos que usar el API key de Apicultur que obtuvimos al comienzo. Líneas 572-974

El primer bloque no tiene mayor misterio. Una vez recogido el parámetro tendremos nuestra palabra almacenada en la variable $word. A partir de ahí, empezamos a pasar nuestra palabra $word por las distintas funciones lingüísticas. El primer paso será lematizar la palabra, es decir, obtener el lema. El lema es la forma en infinitivo/masculino/singular de la palabra, la forma bajo la que la solemos encontrar en un diccionario. Necesitamos el lema de la palabra ya que en algunos campos necesitaremos partir del lema y no de otras formas. En la instrucción de la línea 206 lo que estamos diciendo es que pasemos nuestra palabra $word por la función lematice, y que el resultado lo acumule en la variable $lema_

[php autolinks=”false” gutter=”true” collapse=”false” firstline=”4″ highlight=”true” light=”true” smarttabs=”true” tabsize=”4″ toolbar=”true”]
$lema_=lematice($word);
[/php]

Las líneas que siguen a continuación (207-217) simplemente recorren la respuesta obtenida (el JSON) y guardan la información en variables. Así, en la variable $listaLemas tendremos una lista con todos los posibles lemas de la palabra introducida, y en la variable $listaCat tendremos todas las categorías posibles. A partir de la línea 222 empieza la información relativa a la columna central, la columna de definiciones. En la línea 227, la instrucción

[php autolinks=”false” gutter=”true” collapse=”false” firstline=”4″ highlight=”true” light=”true” smarttabs=”true” tabsize=”4″ toolbar=”true”]
echo "<div class="&quot;colmask">
<div class="&quot;colmid&quot;">
<div class="&quot;colleft&quot;">
<div class="&quot;col1&quot;">
<h2>Definiciones</h2>
"; [/php]

crea la columna central gracias a las sucesivas etiquetas div (esto está sacado tal cual de la plantilla que usamos) y muestra el título del apartado Definiciones. A continuación se llama a la función definaBasica, que proporcionará la definición básica.

[php autolinks=”false” gutter=”true” collapse=”false” firstline=”4″ highlight=”true” light=”true” smarttabs=”true” tabsize=”4″ toolbar=”true”]
$definicionBasicas_ = definaBasica($lema);
[/php]

En caso de que esté disponible la definición básica, se muestra con la instruccción:

[php autolinks=”false” gutter=”true” collapse=”false” firstline=”4″ highlight=”true” light=”true” smarttabs=”true” tabsize=”4″ toolbar=”true”]
echo "<span class="resaltado">".$definicionM."</span>";
[/php]

Seguimos el mismo proceso para obtener las definiciones del diccionario general, llamando a la función

[php autolinks=”false” gutter=”true” collapse=”false” firstline=”4″ highlight=”true” light=”true” smarttabs=”true” tabsize=”4″ toolbar=”true”]
$definiciones_ = defina($lema);
[/php]

y mostrando en la web el resultado obtenido (o mostrando un mensaje de error en caso contrario).

[php autolinks=”false” gutter=”true” collapse=”false” firstline=”4″ highlight=”true” light=”true” smarttabs=”true” tabsize=”4″ toolbar=”true”]
$definiciones = $definiciones_->{‘definiciones’};
if (is_null($definiciones)){
echo "<p><span class=definiciones>No hay definiciones disponibles.</span></p></br>";
echo "</div>";
} else {
foreach($definiciones as $definicion){
echo "<p><span class=definiciones>".$definicion."</span></p></br>";
}
echo "</div>";
}
[/php]

El procedimiento continúa de forma semejante hasta la línea 572, pasando por el resto de funciones lingüísticas y siguiendo siempre el mismo esquema:

  • llamamos a la función correspondiente pasando por parámetro la variable $word
  • si no obtenemos respuesta, mostramos un mensaje que lo indica.
  • si sí tenemos respuesta, recorremos la respuesta (que será el json devuelto por la API), almacenando la información en variables y después mostramos esas variables en la web.
  • cuando corresponda, se van intercalando en las instrucciones echo las etiquetas div para para generar la estructura en tres columnas.

Ejemplo: este es el trozo de código que llama a la función de silabeo, obtiene el resultado y lo muestra en la web:
[php autolinks=”false” gutter=”true” collapse=”false” firstline=”4″ highlight=”true” light=”true” smarttabs=”true” tabsize=”4″ toolbar=”true”]

// SILABEO
//Llamamos a la función que obtiene la info silábica de la palabra
$silabeo_= silabee($word);
//En caso de que no sea posible obtener la info silábica, se mostrará un mensaje que lo indica.
if (!isset($silabeo_)){
echo "No hay silabeo para esta palabra";
}
//En caso de que sí haya info silábica, la mostramos (silabeo, sílaba tónica, número de sílabas, tipo de palabra según acentuación).
if (isset($silabeo_)){
$palabraSilabeada = $silabeo_->{‘palabraSilabeada’};
$silabaTonica = $silabeo_->{‘silabaTonica’};
$posSilabaTonica = $silabeo_->{‘posSilabaTonica’};
$numeroSilabas = $silabeo_->{‘numeroSilabas’};

echo "<span class=resaltado>".$palabraSilabeada."</span></br>";
echo "S&iacute;laba t&oacute;nica: <span class=resaltado>".$silabaTonica."</span></br>";
echo "N&uacute;mero de s&iacute;labas: <span class=resaltado>".$numeroSilabas."</span></br>";

/*La API nos devuelve un número que indica la posición de la sílaba tónica contando desde atrás. El código que viene a continuación "traduce"
ese número, de tal manera que si la posición de la sílaba tónica es 1, lo que se muestra es el mensaje "La palabra es aguda", etc.

*/
if($posSilabaTonica=="1"){
echo "La palabra es <span class=resaltado>aguda</span></br>";
}
if($posSilabaTonica=="2"){
echo "La palabra es <span class=resaltado>llana</span></br>";
}
if($posSilabaTonica=="3"){
echo "La palabra es <span class=resaltado>esdr&uacute;jula</span></br>";
}
if($posSilabaTonica=="4"){
echo "La palabra es <span class=resaltado>sobresdr&uacute;jula</span></br>";
}
echo "</br>";
}
[/php]

A partir de la línea 572 nos encontramos con el tercer bloque del php. En este bloque se declaran las funciones a las que hemos llamado en el segundo bloque. Es decir, es aquí donde se explicitan qué hacen las funciones silabee, lematice, transcriba, defina, etc. ¿Y qué hacen estas funciones? Llamar a las APIs de Apicultur, que son las que suministran el silabeo, la transcripción, las definiciones, etc. Por lo tanton en este punto es donde se establece la relación entre las funciones de php de nuestro diccionario y las APIs de Apicultur. Por ejemplo, en la línea 574 aparece la función silabee:

[php autolinks=”false” gutter=”true” collapse=”false” firstline=”4″ highlight=”true” light=”true” smarttabs=”true” tabsize=”4″ toolbar=”true”]
function silabee($word){

//Este es nuestro API key
$access_key = "ESCRIBE AQUÍ TU API KEY";
//Esta es la URL de llamada a la API de silabeo
$url="https://store.apicultur.com/api/silabeame/1.0.0/".$word;

#Iniciamos curl
$ch = curl_init();

#Pasamos nuestro API Key y se񡬡mos que lo que nos van a devolver es JSON
curl_setopt($ch,CURLOPT_HTTPHEADER,array( ‘Accept: application/json’, ‘Authorization: Bearer ‘ . $access_key ));

#Pasamos la url de la api
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

#Introducimos en una variable el valor que nos devuelve la api
$respuesta = curl_exec($ch);

$http_status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

#Cerrar el recurso cURL y liberar recursos
curl_close($ch);

#Comprobamos el c󤩧o devuelto por la API para ver que todo ha salido correctamente y en caso positivo devolvemos ok
switch ($http_status) {
case ‘200’:
$obj = json_decode($respuesta);
break;
default:
echo "
error al obtener el nivel de la palabra.".$word;
echo "
Error:" .$http_status ;
break;
}
[/php]

Como vemos, esta función contiene toda la maquinaria para llamar a la API de silabeo: la URL, el API key y las instrucciones para guardar el JSON devuelto por la API en una variable y devolver esa variable. Así que cada vez que en el php hemos llamado a estas funciones (lematice, silabee, etc) estas funciones llamaban por detrás a las APIs y nos devolvían el JSON en la variable correspondiente. Estas funciones son, por tanto, las que se encargan de interaccionar con las APIs de Apicultur, hacer la llamada y recoger la respuesta. Es decir, estas funciones son una capa intermedia entre las APIs de Apicultur y nuestro diccionario. Así que por cada API que se use en el diccionario debemos tener una de estas funciones.

A la hora de escribir estas funciones, solo tenemos que asegurarnos de que asignamos nuestra API key de Apicultur (el código alfanumérico que generamos al principio) a la variable $access_key (es decir, sustituímos el “ESCRIBE AQUÍ TU CÓDIGO” por el API key que generaste en Apicultur) y de que llamamos a la URL correcta con los parámetros adecuados en posición adecuada.La información sobre la URL y los parámetros exigidos por cada API la encontrábamos en el perfil de cada API en Apicultur. Dejando al margen la URL y los parámetros, el resto del código de estas funciones siempre es igual.

Llegados a este punto, solo queda personalizar el css a nuestro gusto. El código del css ocupa de la línea 9 a la 167. Hasta la línea 95 aparece la información relacionada con la estructura en tres columnas que obtuvimos de nuestra plantilla. A continuación, aparecen los elementos cuyo diseño hemos querido modificar: por ejemplo, el tipo de letra de la cabecera (headword) es distinta y más grande; también los datos de frecuencia, nivel ABC o transcripción fonética tienen una fuente diferente del resto; algunos datos como la categoría, la definición básica o el tipo de acentuación aparecen con un tamaño algo mayor (marcado con la etiqueta ); a los distintos niveles de frecuencia y complejidad se le han asignado distintos colores siguiendo la gradación de un semáforo (en tonos verdes lo fácil y habitual, hacia el rojo lo difícil o infrecuente). Toda esta información se manipula en el css, y después se asignan las etiquetas pertinentes. En esta web encuentras información sobre css y cómo modificarlo a tu gusto.

Por último, sube el archivo a tu sitio web y tendrás listo tu propio diccionario. Recuerda que este tutorial es sólo una “sugerencia de presentación” y que puedes modificar el código a voluntad, tanto en el diseño como incorporando las APIs que más te interesen.

Si tienes alguna duda, puedes dejar un comentario debajo del post, subir una pregunta al foro de Apicultur, contactarnos por twitter o mandarnos un mail a api{arrobita}apicultur.com

Enlaces interesantes

Tagged with →  
Share →