Mi cuenta

Exportación de datos

ODSLocal Data Export

Exportación de mediciones ODS en CSV · XLSX · JSON con API pública y rate limiting
Versión 1.2.0
PHP ≥ 8.1
WordPress ≥ 6.0
Requiere ODSLocal Municipios
CC BY 4.0

1. Qué hace

Add-on de exportación abierta para ODSLocal Municipios. Cualquier visitante (o sistema externo) puede descargar las mediciones aprobadas en:

  • CSV — UTF-8 con BOM, cabecera RFC-compliant, compatible con Excel.
  • XLSX — Excel nativo (requiere PhpSpreadsheet) o fallback automático a CSV.
  • JSON — objetos estructurados con metadatos.

Todos los ficheros incluyen cabecera con nombre de la organización, URL, licencia CC BY 4.0 y timestamp UTC.

2. Instalación

  1. Asegúrate de tener ODSLocal Municipios activo.
  2. (Opcional) Para XLSX real: composer require phpoffice/phpspreadsheet en la raíz de WordPress. Sin esto, los endpoints XLSX hacen fallback a CSV.
  3. Sube odslocal-data-export/ a wp-content/plugins/.
  4. Actívalo. Se crea la tabla wp_odslocal_export_log y aparece el submenú Municipios → Exportar datos.

3. Shortcode de panel público

        


            
            

                                

                    Plataforma ODSLocal España — Datos Abiertos ODS                

            


            
            

                
Por municipio


                

                    

                        
                        
                    


                    

                    
                


                

                    Selecciona un municipio para habilitar la descarga.                


                
            


            
            

                
Por indicador


                

                    

                    

                    
                


                

                    
                        📥 CSV                    
                    
                        📥 JSON                    
                

            


            
            

                

                    Datos publicados por Plataforma ODSLocal España bajo licencia CC BY 4.0.                                        — 
                        https://odslocal.es

Renderiza un panel completo con:

  • Búsqueda de municipio con autocompletado (mín. 2 caracteres) accesible por teclado (↑/↓/Enter/Esc).
  • Filtros por grupo ODS y año.
  • Botones de descarga por formato (CSV / XLSX / JSON) para el municipio seleccionado.
  • Descarga por indicador: selecciona un indicador y año, descarga valores para todos los municipios.

El panel funciona sin autenticación. Solo devuelve mediciones approved.

4. Panel administrador

En Municipios → Exportar datos (requiere manage_options):

  • Estadísticas — total de mediciones aprobadas, municipios cubiertos, indicadores.
  • Descarga en lote por año — en un click, todas las mediciones aprobadas de un año concreto.
  • Historial de exportaciones — últimos logs con filtros por usuario, tipo, fecha.
  • Identidad de la organización — aviso amarillo si no está configurada; enlace directo a Ajustes → Contributor Profiles.

5. Endpoints REST

Namespace base: /wp-json/odslocal-export/v1.

Método Ruta Qué devuelve
GET /municipality/{code_ine}/csv Todos los indicadores aprobados del municipio en CSV.
GET /municipality/{code_ine}/json Idem en JSON.
GET /municipality/{code_ine}/xlsx Idem en XLSX (o fallback CSV).
GET /indicator/{indicator_key}/csv?year=YYYY Un indicador para todos los municipios.
GET /indicator/{indicator_key}/json?year=YYYY Idem JSON.
GET /bulk/csv?year=YYYY Descarga completa por año (1 req / 60 s / IP).
GET /territories?q=… Autocompletado (mín. 2 chars).

Parámetros opcionales en /municipality/*: ods_group, year.

Ejemplos

# CSV completo de Vigo
curl -O "https://odslocal.es/wp-json/odslocal-export/v1/municipality/36057/csv"

# JSON solo de ODS3 en Vigo
curl "https://odslocal.es/wp-json/odslocal-export/v1/municipality/36057/json?ods_group=ODS3"

# Todos los datos aprobados del año 2023
curl -O "https://odslocal.es/wp-json/odslocal-export/v1/bulk/csv?year=2023"

6. Formatos de salida

6.1 CSV

  • Codificación: UTF-8 con BOM (para que Excel abra sin caracteres raros).
  • Separador: coma.
  • Nueva línea: CRLF.
  • Campos con coma, comilla o CR/LF van entre comillas dobles con escape "".
  • Protección Formula Injection: cualquier celda textual que empiece por =, +, -, @, TAB o CR se prefija con ' (comilla simple). Evita que Excel ejecute fórmulas arbitrarias.

6.2 XLSX

Si PhpSpreadsheet está disponible, se genera un .xlsx con una hoja de datos + hoja de metadatos. Si no, el servidor devuelve el CSV con MIME application/vnd.ms-excel (Excel lo abre igualmente).

6.3 JSON

{
  "meta": {
    "organisation": "Plataforma ODSLocal España",
    "url": "https://odslocal.es",
    "license": "CC BY 4.0",
    "exported_at": "2026-04-21T14:30:05Z"
  },
  "data": [
    {
      "code_ine": "36057",
      "name": "Vigo",
      "indicator_key": "ods_ods_3_1_1__esperanza_de_vida_al_nacer",
      "year": 2023,
      "value": 83.2,
      "source": "INE"
    }
  ]
}

7. Identidad de la organización

El plugin no tiene sus propios ajustes. Lee la identidad desde ODSLocal Contributor Profiles (porque la carta y el export deben coincidir):

Opción Dónde se configura
odslocal_profiles_org_name Ajustes → Contributor Profiles → Organización.
odslocal_profiles_org_address Idem.
odslocal_profiles_logo_url Idem.
odslocal_profiles_signature_name Idem → Firma.
odslocal_profiles_signature_title Idem.

Si org_name está vacío, se usa get_bloginfo('name') y se muestra un aviso sólo en las pantallas del propio plugin.

8. Licencia y atribución de datos

Todos los ficheros llevan una cabecera (comentarios CSV, celdas top en XLSX, bloque meta en JSON) con:

  • Nombre de la organización.
  • URL de la plataforma.
  • Licencia: Creative Commons CC BY 4.0.
  • Timestamp UTC de la exportación.

La atribución correcta al reutilizar los datos es: «Datos publicados por [Organización] bajo CC BY 4.0 — [URL].»

9. Rate limiting

El endpoint /bulk/csv (descarga completa por año) está limitado a 1 request / 60 segundos / IP para proteger el servidor de scrapers agresivos.

  • Cuando se excede, la respuesta es 429 Too Many Requests con header Retry-After: 60.
  • El resto de endpoints (municipio único, indicador único, autocompletado) no tienen rate limit.

10. Seguridad

  • CSV Formula Injection neutralizada (' prepended).
  • Header injection: X-ODSLocal-Org hace strip de rn.
  • Content-Disposition: ASCII fallback + RFC 5987 filename*=UTF-8''… para nombres con caracteres especiales.
  • IP logging: valida con FILTER_VALIDATE_IP; prefiere REMOTE_ADDR; sólo consulta headers forwarded si hay proxy real.
  • Sólo datos aprobados: no se expone nada en estados draft, pending o rejected.
  • Sin autenticación por diseño — los datos son abiertos bajo CC BY 4.0.

11. Auditoría

Cada exportación se registra en wp_odslocal_export_log:

Campo Significado
user_id 0 si es visitante anónimo.
export_type csv_municipality, json_indicator, xlsx_bulk, etc.
params JSON con los filtros usados.
rows Número de filas incluidas.
ip IP validada.
created_at Timestamp.

12. Traducciones

  • Text domain: odslocal-export, idioma de origen: español.
  • languages/odslocal-export.pot — plantilla.
  • odslocal-export-gl_ES.po/.mo — galego.
  • Para un nuevo idioma: duplicar POT, traducir, compilar con Poedit o wp i18n make-mo.

13. Solución de problemas

XLSX descarga como CSV

Es el fallback automático. Instala phpoffice/phpspreadsheet vía Composer en la raíz de WordPress para XLSX nativo.

429 al descargar bulk

Esperado. Espera 60 s o usa endpoints más granulares (por municipio o indicador).

El CSV abre con caracteres raros en Excel

El fichero ya incluye BOM UTF-8. Si aun así falla, en Excel elige Datos → Desde texto y selecciona codificación 65001 UTF-8.

Los datos aparecen como «Array» en el historial

Bug corregido en 1.2.0 — si ves este síntoma, actualiza.

Saltar al contenido principal