API Oasis WiFi versión 2.0

1. API de Puntos WI-FI
V2.0
Telefónica Móviles España
Movilforum
10/04/2012
Madrid

2. API de Puntos Wi- Fi. V2.0
Índice
1.
INTRODUCCIÓN ..................................................................................................................................................... 2
2.
LISTADO DE FUNCIONES DE LA API .............................................................................................................. 3
3.
DESCRIPCIÓN DE CAMPOS ............................................................................................................................... 5
3.1 LISTADO DE PUNTOS WI-FI ...................................................................................................................................... 5
3.2 OBTENCIÓN DEL BSSID ............................................................................................................................................ 5
3.3 OBTENCIÓN DE UN PUNTO WI-FI .............................................................................................................................. 5
3.4 ACTUALIZACIÓN DE UN PUNTO WI-FI ...................................................................................................................... 5
3.5 ENVÍO DE INCIDENCIAS ............................................................................................................................................. 6
4. EJEMPLO DE USO CON PHP................................................................................................................................. 8
Movilforum -1

3. API de Puntos Wi- Fi. V2.0
1. INTRODUCCIÓN
El objeto de este documento es describir la API de puntos WI-FI. Se trata de una API de lectura y escritura
de datos a través de la cual los usuarios pueden utilizar la funcionalidad de la aplicación de Puntos WI-FI
desde terceras aplicaciones para distintos usos. Se trata de una API REST, a la que se accede mediante el
protocolo HTTP de manera autenticada mediante sistema de token secreto, y a la que se pueden ordenar
acciones a través de los mecanismos de los que dispone el protocolo HTTP: GET, POST, PUT y DELETE.
Como respuesta a las peticiones la API devuelve resultados en formato JSON.
La API está accesible desde http://wifi.movilforum.com/api. La siguiente sección contiene un listado
detallado de acciones que se pueden ejecutar a través de la misma.
Movilforum -2

4. API de Puntos Wi- Fi. V2.0
2. LISTADO DE FUNCIONES DE LA API
URL Método Descripción Parámetros Resultado
400 – Errores de validación de los
parámetros
404 – Not Found
200 - { “Hotspot":[
{“IdDistribuidor”:id_hotspot,
“CIH”: cih_hotspot,
“Nombre”:name_hotspot,
“Tipologia”: type_hotspot,
“Direccion”: address_hotspot,
http://wifi.movilforum.com/a api_key “Localidad”: city_hotspot,
Obtiene los puntos WI-
pi latitude,longitude “Provincia”: province_hotspot,
GET FI cercanos a esa
api_key/hotspots/list/latitud count “CodigoPostal”: zipCode_hotspot,
localización
e,longitude/count “Estado”: state_hotspot,
“TipoAcceso”: accessType_hotspot,
“AreasCubiertas”:area_hotspot,
“GPSlat”: latitude_hotspot,
“GPSlong”: longitude_hotspot,
“DescLocalizacion”: description”
},
...
]}
400 – Errores de validación de los
parámetros
404 – “Not Found”
http://wifi.movilforum.com/ Obtiene el BSSID
api_key
api/api_key/hotspots/bssid/ GET ubicado en el punto
latitude,longitue
latitude,longitude enviado
200 – { “BSSID”:”bssid_name”}
Movilforum -3

5. API de Puntos Wi- Fi. V2.0
400 – Errores de validación de los
parámetros
404 – “Not Found”
200 - { “Hotspot":[
api_key {“IdDistribuidor”:id_hotspot,
idDistribuidor “CIH”: cih_hotspot,
“Nombre”:name_hotspot,
“Tipologia”: type_hotspot,
http://wifi.movilforum.com/ Obtiene el Punto WI-FI
“Direccion”: address_hotspot,
api/api_key/hotspots/idDist GET asociado a un
“Localidad”: city_hotspot,
ribuidor distribuidor
“Provincia”: province_hotspot,
“CodigoPostal”: zipCode_hotspot,
“Estado”: state_hotspot,
“TipoAcceso”: accessType_hotspot,
“AreasCubiertas”:area_hotspot,
“GPSlat”: latitude_hotspot,
“GPSlong”: longitude_hotspot,
“DescLocalizacion”: description”
}]}
api_key 400 - "Bad request"
idDistribuidor
cih
nombre
tipologia
direccion
localidad
provincia
Actualiza los datos de
http://wifi.movilforum.com/ codigoPostal 200 – {“Codigo”:success}
un punto WI-FI
api/hotspots/update POST estado
tipoAcceso
areas
gpsLat
gpsLong
descripcion
api_key
bssid 400 - Errores de validación de los
Envía un nuevo gpsLat elementos de la incidencia
formulario de gpsLong
http://wifi.movilforum.com/
POST incidencias para tipoError
api/hotspots/report
notificar el error direccion 200 - {"result": "Response successfully
asociado a un localidad created"}
Punto WI-FI codigoPostal
comentarios
Movilforum -4

6. API de Puntos Wi- Fi. V2.0
3. DESCRIPCIÓN DE CAMPOS
A continuación se describen los campos utilizados en cada una de las llamadas de la API.
3.1 Listado de Puntos WI-FI
Llamada: http://wifi.movilforum.com/api/api_key/hotspots/list/latitude,longitude/count
Esta llamada utiliza varios parámetros: la posición, la cual está representada por los valores en decimal de
latitud y longitud separados por una coma y la cantidad de puntos que se quieren recuperar. Los puntos se
devolverán ordenados de mayor a menor proximidad a la posición indicada.
3.2 Obtención del BSSID
Llamada: http://wifi.movilforum.com/api/api_key/hotspots/bssid/latitude,longitude
Al igual que la llamada para obtener el listado de puntos WI-FI, para obtener el BSSID de un punto WI-FI
dada su localización se necesitan las coordenadas (los valores de latitud y longitud separados por una
coma).
3.3 Obtención de un Punto WI-FI
Llamada: http://wifi.movilforum.com/api/api_key/hotspots/idDistribuidor
Esta llamada recibe como parámetro el identificador del distribuidor asociado al punto WI-FI que se quiere
recuperar.
3.4 Actualización de un Punto WI-FI
Llamada: http://wifi.movilforum.com/api/hotspots/update
Los parámetros necesarios en esta llamada son los siguientes:
- idDistribuidor: identificador del punto WI-FI.
- cih: número administrativo del punto WI-FI.
- nombre: denominación del punto WI-FI.
- tipologia: caracterización del punto WI-FI. Puede tomar los siguientes valores:
o Hoteles 4 o 5 estrellas
o Hoteles hasta 3 estrellas
Movilforum -5

7. API de Puntos Wi- Fi. V2.0
o Restaurantes y cafeterías
o Escuelas de negocios y universidades
o Recintos portuarios
o Aeropuertos y estaciones
o Centros de convenciones y recintos feriales
o Camaras de comercio, clubes sociales y otros
- direccion: domicilio de instalación.
- localidad: localidad del domicilio de instalación.
- provincia: provincia del domicilio de instalación.
- codigoPostal: código postal del domicilio de instalación.
- estado: estado de tramitación del punto WI-FI. Puede tomar los siguientes valores:
o OPERATIVO
o EN INSTALACIÓN
- tipoAcceso: UNIPUNTO, MULTIPUNTO, COMPACTO.
- areas: descripción de las zonas en las que hay cobertura.
- gpsLat: latitud en decimal de la ubicación del punto WI-FI.
- gpsLong: longitud en decimal de la ubicación del punto WI-FI.
- descripcion: breve descripción de la ubicación (máximo 50 caracteres).
3.5 Envío de incidencias
Llamada: http://wifi.movilforum.com/api/hotspots/report
Para llevar a cabo el envío de una incidencia, son necesarios los siguientes campos:
- bssid: el nombre que identifica el punto WI-FI al que se refiere la incidencia.
- gpsLat: latitud del punto WI-FI en valor decimal.
- gpsLong: longitud del punto WI-FI en valor decimal.
- tipoError: el tipo de error detectado. Se debe utilizar el valor númerico asociado a cada error.
Los posibles valores son:
o 0: SSID de Telefónica no existe
o 1: Conexión WI-FI muy lenta
o 2: Imposible establecer conexión WI-FI
o 3: Conexión WI-FI se corta
o 4: Zona WI-FI no señalizada
o 5: Imposible obtener PIN de acceso al servicio
- direccion: dirección en la que está ubicado el punto WI-FI.
Movilforum -6

8. API de Puntos Wi- Fi. V2.0
- localidad: localidad en la que se encuentra el punto WI-FI.
- codigoPostal: código postal de la ubicación del punto WI-FI.
- comentarios: breve descripción del problema encontrado.
Movilforum -7

9. API de Puntos Wi- Fi. V2.0
4. EJEMPLO DE USO CON PHP
Por último se muestra un ejemplo de consumo de la API a través de PHP. La función ejecutada es
http://wifi.movilforum.com/api/api_key/hotspots/list, con la que se obtienen los puntos WI-FI cercanos a la
posición dada. Para este ejemplo obtendremos la lista de los 10 puntos más cercanos a las coordenadas
latitud: 40.430223634508 y longitud: -3.724365234375. Como se puede observar, las coordenadas son
números decimales. El api token utilizado es: 1cdc6ccea9924892ec5e4d0d29f48db6
Para ejecutar la llamada a la API habrá que hacer un GET a:
http://wifi.movilforum.com/api/api_key/hotspots/list/40.430223634508,-3.724365234375/10.
El código PHP para ejecutar la llamada sería el siguiente:
<?php
$request =
'http://wifi.movilforum.com/api/1cdc6ccea9924892ec5e4d0d29f48db6/hotspots/list/40.4
30223634508,-3.724365234375/10';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $request);
curl_setopt($ch, CURLOPT_HTTPGET, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array ('Accept: application/json'));
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
$result = curl_exec($ch);
$resultArray = curl_getinfo($ch);
curl_close($ch);
if($resultArray['http_code'] == "200"){
echo 'Response sent!: <br><b>' . print_r($result, true) . '</b>';
}else {
echo 'Error getting Puntos WI-FI API!: <br><b>' . $resultArray['http_code'] .
': ' . print_r($result, true) . '</b>';
}
?>
Movilforum -8