andreshg112 / datos-abiertos

Paquete para Laravel que consulta la API de Datos Abiertos del Gobierno de Colombia.

Datos Abiertos de Colombia para Laravel

Este paquete encapsula las consultas a la API de Datos Abiertos del Gobierno de Colombia.

Recursos implementados

• ESTABLECIMIENTOS EDUCATIVOS DE PREESCOLAR, BÁSICA (\Andreshg112\DatosAbiertos\Facades\Colegios).

• Códigos de la Divisón Político-Administrativa del país (\Andreshg112\DatosAbiertos\Facades\Divipola).

• Organismos de Tránsito (\Andreshg112\DatosAbiertos\Facades\OrganismosTransito).

Si deseas que desarrolle una consulta a otro recurso de datos.gov.co, puedes realizar la petición en los Issues.

Requisitos

• Laravel >= 5.5
• PHP >= 7.1.x

Si quieres soporte para una versión inferior a las especificadas, por favor deja la petición en los Issues y veré qué puedo hacer.

Instalación

Puedes instalar el paquete a través de composer:

composer require andreshg112/datos-abiertos

Este paquete usa Laravel Package Discovery por lo que, si usas Laravel 5.5 o superior, no debes preocuparte agregar \Andreshg112\DatosAbiertos\DatosAbiertosServiceProvider al listado de providers en el archivo config/app.php.

Uso

Uso básico

Cada recurso hereda de \Andreshg112\DatosAbiertos\Datasets\BaseDataset, el cual tiene el método getData($filterOrSoqlQuery = '') que permite consultar todos los registros del recurso o filtrar de acuerdo a los parámetros.

Por ejemplo:

use Andreshg112\DatosAbiertos\Facades\Divipola;

// Listado total de municipios:
$data = Divipola::getData();

Uso de filtros

En la definición de la API de Divipola puedes encontrar los detalles del recurso y el uso de filtros.

Advertencia: La API de datos.gov.co distingue mayúsculas y minúsculas. Por lo tanto si buscas, por ejemplo, nom_mpio=valledupar no aparecerá porque debe tener la V mayúscula.

use Andreshg112\DatosAbiertos\Facades\Divipola;

// Para filtrar por código de departamento puedes hacer cualquiera de las siguientes formas:

$filterOrSoqlQuery = 'cod_depto=20'; // esta

$filterOrSoqlQuery = ['cod_depto' => '20']; // o esta

$data = Divipola::getData($filterOrSoqlQuery);

Este paquete usa allejo/php-soda para realizar las peticiones a los recursos de datos.gov.co usando Socrata Open Data API (SODA), por lo tanto $filterOrSoqlQuery puede ser cualquiera de los parámetros aceptados por la función \allejo\Socrata\SodaDataset::getData(filterOrSoqlQuery). Para usar filtros avanzados, dirígete a su documentación (en inglés).

Extender la funcionalidad

Macroable

La clase padre \Andreshg112\DatosAbiertos\Datasets\BaseDataset de los recursos (datasets) usa el trait \Spatie\Macroable\Macroable de spatie/macroable, por lo que puedes extender la funcionalidad de cada recurso de la siguiente manera:

// En el archivo app/Providers/AppServiceProvider.php:

use Andreshg112\DatosAbiertos\Facades\OrganismosTransito;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        OrganismosTransito::macro('whereEstadoLimit', function($estado, $limit){
            $filter = [
                '$where' => "estado = '$estado'", // https://dev.socrata.com/docs/queries
                '$limit' => $limit, // 1, 2, 3, etc.
            ];

            return $this->getData($filter);
        });
    }
}

// Y luego, en cualquier otra parte:
$data = OrganismosTransito::whereEstadoLimit('ACTIVO', 3);

Para más información, dirígete a su documentación.

Crear tu propio recurso

Puedes crear tu propio dataset que herede de \Andreshg112\DatosAbiertos\Datasets\BaseDataset de la siguiente manera:

Este recurso será implementado en el paquete, solo se coloca de ejemplo.

<?php

use Andreshg112\DatosAbiertos\Datasets\BaseDataset;

namespace App\Datasets;

/**
 * https://www.datos.gov.co/Educaci-n/colegios/u3ch-n6ec
 */
class Colegios extends BaseDataset
{
    public function getColumns()
    {
        return [
            'a_o', // año.
            'calendario',
            'codigo_etc', // nombre_Rector
            'codigodepartamento', 'codigoestablecimiento',
            'codigomunicipio', 'correo_electronico', 'direccion', 'discapacidades', 'especialidad',
            'estrato_socio_economico', 'etnias', 'grados', 'idiomas', 'internado', 'jornada',
            'matricula_contratada', 'modelos', 'modelos_educativos', 'niveles', 'nombredepartamento',
            'nombreestablecimiento', 'nombremunicipio', 'numero_de_sedes', 'prestador_de_servicio',
            'propiedad_planta_fisica', 'resguardo', 'secretaria', 'telefono', 'tipo_establecimiento',
            'zona',
        ];
    }

    protected function getDatasetIdentifier()
    {
        // El código del recurso, que es la última parte de la URL sin el .json
        // https://www.datos.gov.co/resource/xax6-k7eu.json
        return 'xax6-k7eu';
    }

    protected function getUniqueColumn()
    {
        return 'codigoestablecimiento';
    }
}

La API no acepta tildes, ñ o caracteres especiales en los nombres.

Luego, tendrás que hacer una fachada para la clase y está listo para usarse. Puede ser una fachada en tiempo real colocando el namespace Facades antes del namespace de la clase, así:

use Facades\App\Datasets\Colegios;

Métodos de los recursos (datasets)

Todos los recursos permiten el filtrado avanzado a través del método getData($filterOrSoqlQuery), pero para búsquedas simples, se puede usar el método where(string $column, $value) de la siguiente manera:

use Facades\App\Datasets\Colegios; // Fachada en tiempo real.

$data = Colegios::where('modelos_educativos', 'EDUCACIÓN TRADICIONAL');

Las columnas del recurso o dataset (ya sea incluido o personalizado), que se indican en getColumns(), permiten acceden dinámicamente a métodos de acuerdo con los nombres transformados en camelCase, y el prefijo where con la primera letra mayúscula por ejemplo:

use Facades\App\Datasets\Colegios;
use Andreshg112\DatosAbiertos\Facades\Divipola;
use Andreshg112\DatosAbiertos\Facades\OrganismosTransito;

// nombredepartamento
Colegios::whereNombredepartamento('Cesar'); // d minúscula porque no tiene subguión.

// nom_mpio
Divipola::whereNomMpio('Valledupar'); // M mayúscula porque tiene subguión.

// categor_a
OrganismosTransito::whereCategorA('A'); // A mayúscula porque tiene un subguión antes.

Todos los métodos retornan un vector de registros (array de arrays). Si se desea consultar un solo registro a través de la columna con valor único, entonces se hace uso de la función find($uniqueValue). Esto hace que el método solo retorne un solo registro (array) en vez de un vector de registros. Por ejemplo:

use Andreshg112\DatosAbiertos\Facades\Colegios; // Esta es la implementación incluída.

$data = Colegios::find(147707000156);

// Es equivalente a:
$data = Colegios::whereCodigoestablecimiento(147707000156)[0] ?? null;

// y a:
$data = Colegios::where('codigoestablecimiento', 147707000156)[0] ?? null;

Columnas de valor único:

• Colegios: codigo_establecimiento
• Divipola: cod_mpio
• OrganismosTransito: cod_divipola

Los nombres de las columnas están especificados en la definición de la API de cada recurso en la plataforma de Datos Abiertos.

Pruebas

composer test

Registro de cambios

Por favor, mira el listado de Versiones para obtener más información sobre lo que ha cambiado recientemente.

Contribuir

Por favor, mira el archivo CONTRIBUTING (en inglés) para más detalles.

Seguridad

Si descubres una vulnerabilidad o fallo relacionado con seguridad, te agradezco que por favor me escribas a [email protected] en vez de hacerlo en el registro de errores.

Créditos

• Andrés Herrera García
• All Contributors

Licencia

Licencia MIT. Por favor, mira el archivo License File (en inglés) para más información.

Laravel Package Boilerplate

Este paquete fue generado usando Laravel Package Boilerplate.