menjometre-cli

Eina de línia de comandes per consultar les dades públiques de Menjometre — l'observatori independent de subvencions i contractes públics a Catalunya.

IMPORTANT PER A AGENTS: Usa sempre --json per obtenir sortida estructurada parsejable. La sortida per defecte és una taula formatejada per humans.

Instal·lació ràpida

npm install -g menjometre-cli   # instal·lació global
npx menjometre-cli stats        # o executar sense instal·lar

Requereix Node.js >= 18. No cal autenticació ni clau API.

Arbre de decisió per a agents

Vull informació sobre una entitat concreta?
├── Tinc el CIF (ex: Q2866001G) → menjometre entity Q2866001G --json
├── Tinc el slug (ex: CREU-ROJA) → menjometre entity CREU-ROJA --json
├── Tinc només el nom → menjometre search "Creu Roja" --json
│                        └── Agafa el camp `identifier` del primer resultat
│                            └── menjometre entity <identifier> --json
└── Vull les subvencions/contractes individuals?
    ├── menjometre grants <identifier> --json
    └── menjometre contracts <identifier> --json

Vull dades globals?
├── Xifres del dataset → menjometre stats --json
├── Ranking d'entitats → menjometre top --limit 50 --json
└── Equivalències d'un import → menjometre equivalencies 5000000 --json

Conceptes clau

Identificadors d'entitat

Cada entitat té fins a 3 identificadors. L'API accepta qualsevol dels tres:

| Tipus | Exemple | Descripció | |---|---|---| | Slug | CRUZ-ROJA-ESPANOLA | Nom normalitzat (majúscules, sense accents, guions). És el més comú. | | CIF | Q2866001G | Codi d'identificació fiscal. Pot ser null (~85% entitats no en tenen). | | Slug en minúscules | cruz-roja-espanola | També funciona, es resol automàticament. |

L'API resol l'identificador en 4 passos: CIF → slug exacte → slug en majúscules → taula de redireccions de slugs antics.

Què és el Menjometre Score

Puntuació de 0 a 100 que mesura patrons estadístics en la distribució de fons públics. NO indica irregularitat, corrupció ni frau — és un indicador de concentració i recurrència.

| Component | Camp JSON | Pes | Què mesura | |---|---|---|---| | Volum | score_volume | 20-25% | Percentil de l'import total rebut | | Concentració | score_concentration | 20-25% | Índex HHI de departaments (1 dept = 100) | | Recurrència | score_recurrence | 20-25% | Anys consecutius amb subvencions | | Dominància | score_dominance | 20-25% | Quota màxima en una categoria de finalitat | | Rendició de comptes | score_accountability | 0-20% | Registres, comptes, dependència. Pot ser null. |

• 5 components al 20% si score_accountability existeix; 4 al 25% si és null.
• Llindar: cal 3+ subvencions I 5.000+ EUR. Per sota, menjometre_score = 0.

Dades disponibles

• 536.000+ entitats (empreses, associacions, entitats públiques, persones)
• 19,7M subvencions (28.000M EUR) — font: RAISC + BDNS (2016-2026)
• 1,5M contractes públics (75.000M EUR) — font: Contractes.cat (2015-2026)
• 371.000 entitats puntuades amb Menjometre Score

Referència de comandes

search — Cercar entitats

Cerca per nom o CIF. Retorna fins a 8 resultats ordenats per import total descendent.

menjometre search "Creu Roja" --json

Resposta JSON (array):

[
  {
    "identifier": "CRUZ-ROJA-ESPANOLA",
    "name": "CREU ROJA A GIRONA",
    "cif": "Q2866001G",
    "total_amount": 54088736.82,
    "municipality": null
  },
  {
    "identifier": "CREU-ROJA-A-CATALUNYA",
    "name": "CREU ROJA A CATALUNYA",
    "cif": null,
    "total_amount": 2088460.53,
    "municipality": null
  }
]

Camp clau: identifier — és el slug que has de passar a entity, grants o contracts.

entity — Perfil complet d'una entitat

Accepta CIF, slug o slug en minúscules.

menjometre entity CRUZ-ROJA-ESPANOLA --json
menjometre entity Q2866001G --json
menjometre entity cruz-roja-espanola --json

Resposta JSON (objecte):

{
  "name": "CREU ROJA A GIRONA",
  "cif": "Q2866001G",
  "slug": "CRUZ-ROJA-ESPANOLA",
  "beneficiary_type": "JSA",
  "org_type": null,
  "municipality": null,
  "comarca": "Barcelonès",
  "vegueria": null,
  "total_amount": 54088736.82,
  "total_grants": 275,
  "first_grant_year": 2019,
  "last_grant_year": 2025,
  "total_contracts": 231,
  "total_contract_amount": 5390787.81,
  "sole_source_pct": 88.31,
  "fragmentation_risk": 1.3,
  "total_public_funds": 59479524.63,
  "menjometre_score": 67.15,
  "score_volume": 99.99,
  "score_concentration": 54.83,
  "score_recurrence": 100,
  "score_dominance": 3.13,
  "score_accountability": 77.78,
  "rank": 212,
  "percentile": 99.96,
  "is_premsa": false,
  "is_tercer_sector": false,
  "is_person": false,
  "website": null,
  "org_description": null,
  "equivalencies": [
    { "label": "Habitatges socials", "icon": "🏗️", "count": 339, "annual_cost": 175000 },
    { "label": "Ambulàncies equipades", "icon": "🚑", "count": 258, "annual_cost": 230000 }
  ],
  "url": "https://menjometre.cat/entitat/cruz-roja-espanola"
}

Camps importants per a agents:

| Camp | Tipus | Notes | |---|---|---| | total_public_funds | number | Xifra principal: subvencions + contractes combinats | | menjometre_score | number | 0-100, 0 = per sota del llindar o sense puntuar | | rank | number|null | Posició al ranking per fons públics. null si no rankejat | | percentile | number|null | Percentil (99.96 = top 0.04%) | | sole_source_pct | number|null | % contractes per adjudicació directa (0-100) | | equivalencies | array | Llista d'equivalències en serveis públics per total_public_funds | | url | string | Enllaç directe a la fitxa web de l'entitat | | cif | string|null | Pot ser null — ~85% d'entitats no tenen CIF | | score_accountability | number|null | null = no hi ha dades de rendició de comptes |

Error (entitat no trobada):

{"error": "Entity not found"}

HTTP 404.

top — Ranking d'entitats

menjometre top --json                              # top 10 per puntuació
menjometre top --limit 50 --sort amount --json     # top 50 per import
menjometre top --type premsa --json                # només mitjans de comunicació
menjometre top --type tercer_sector --json         # només tercer sector
menjometre top --sort contracts --json             # per import de contractes

| Paràmetre | Valors | Per defecte | |---|---|---| | --limit | 1-100 | 10 | | --sort | score, amount, contracts | score | | --type | all, premsa, tercer_sector | all |

Resposta JSON (array d'objectes):

[
  {
    "slug": "BENEF-NO-PUBLICABLE-DEPARTAMENT-DE-DRETS-SOCIALS-I-INCLUSIO",
    "cif": null,
    "name": "Benef. no publicable (Departament de Drets Socials i Inclusió)",
    "beneficiary_type": "FSA",
    "municipality": null,
    "comarca": "Barcelonès",
    "total_amount": 5310567577.85,
    "total_grants": 13751283,
    "total_contracts": 0,
    "total_contract_amount": 0,
    "total_public_funds": 5310567577.85,
    "menjometre_score": 0,
    "is_premsa": false,
    "is_tercer_sector": false,
    "is_person": false,
    "url": "https://menjometre.cat/entitat/benef-no-publicable-departament-de-drets-socials-i-inclusio"
  }
]

Nota: les entitats amb menjometre_score: 0 poden tenir imports molt alts però no complir el llindar de puntuació (3+ subvencions, 5K+ EUR) o ser entitats especials (beneficiari no publicable, persona física agregada).

stats — Resum del dataset

menjometre stats --json

Resposta JSON (objecte):

{
  "total_entities": 536384,
  "total_grants": 19769489,
  "total_amount": 28258544420.15,
  "total_contracts": 1542650,
  "total_contract_amount": 75478640687.47,
  "scored_entities": 371042,
  "date_range": { "first_year": 2022, "last_year": 2026 },
  "last_sync": null
}

| Camp | Descripció | |---|---| | total_amount | EUR totals en subvencions (no inclou contractes) | | total_contract_amount | EUR totals en contractes públics | | scored_entities | Entitats amb menjometre_score > 0 | | date_range | Rang d'anys del període recent (últims 3 anys complets) | | last_sync | Timestamp ISO de l'última sincronització, o null |

equivalencies — Calculadora d'equivalències

Converteix un import en EUR a equivalències en serveis públics catalans. Càlcul pur, no consulta la base de dades.

menjometre equivalencies 1000000 --json

Resposta JSON:

{
  "amount": 1000000,
  "equivalencies": [
    { "key": "t_jove", "label": "Abonaments T-jove anuals", "icon": "🚌", "count": 5681, "annual_cost": 176, "tier": "personal", "source": "ATM, 44€/trimestre × 4" },
    { "key": "teachers", "label": "Mestres d'escola/any", "icon": "👩‍🏫", "count": 23, "annual_cost": 42000, "tier": "professional", "source": "Dept. Educació 2024" },
    { "key": "housing", "label": "Habitatges socials", "icon": "🏗️", "count": 5, "annual_cost": 175000, "tier": "infrastructure", "source": "VPO 2024" }
  ]
}

Només retorna equivalències amb count >= 1. Ordenades de menor a major cost anual.

Totes les equivalències disponibles:

| Clau | Descripció | Cost anual | Nivell | |---|---|---|---| | t_jove | Abonaments T-jove anuals | 176 EUR | personal | | textbooks | Lots de llibres de text | 300 EUR | personal | | school_lunches | Menjadors escolars/any (per nen) | 1.320 EUR | personal | | scholarships | Beques universitàries/any | 6.000 EUR | personal | | daycare | Places llar d'infants/any | 9.000 EUR | personal | | eldercare | Places de residència/any | 24.000 EUR | professional | | nurses | Infermers/any | 35.000 EUR | professional | | teachers | Mestres d'escola/any | 42.000 EUR | professional | | mossos | Mossos d'Esquadra/any | 45.000 EUR | professional | | bombers | Bombers/any | 48.000 EUR | professional | | doctors | Metges/any | 55.000 EUR | professional | | solar | Instal·lacions solars (30kWp) | 45.000 EUR | infrastructure | | playground | Parcs infantils nous | 120.000 EUR | infrastructure | | housing | Habitatges socials | 175.000 EUR | infrastructure | | bike_lane | Km de carril bici urbà | 200.000 EUR | infrastructure | | ambulance | Ambulàncies equipades | 230.000 EUR | infrastructure | | school_renovation | Renovacions d'escola | 620.000 EUR | infrastructure | | mri | Ressonàncies magnètiques | 1.500.000 EUR | infrastructure | | school | Escoles públiques noves | 7.300.000 EUR | infrastructure | | train | Trens de Rodalies | 6.650.000 EUR | infrastructure |

grants — Llistat de subvencions

menjometre grants CRUZ-ROJA-ESPANOLA --json
menjometre grants CRUZ-ROJA-ESPANOLA --year 2024 --json

Resposta JSON (array):

[
  {
    "grant_year": 2024,
    "department": "Departament de Drets Socials i Inclusió",
    "purpose": "Atenció a persones sense llar",
    "amount": 150000
  }
]

contracts — Llistat de contractes

menjometre contracts CRUZ-ROJA-ESPANOLA --json
menjometre contracts Q2866001G --year 2023 --json

Resposta JSON (array):

[
  {
    "contract_year": 2023,
    "organ": "Ajuntament de Barcelona",
    "description": "Servei d'atenció social",
    "amount": 85000,
    "contract_type": "Serveis"
  }
]

Fluxos complets per a agents

Flux 1: "Quant ha rebut l'entitat X?"

# Pas 1: cercar per nom (si no tenim el slug)
menjometre search "Diputació de Barcelona" --json
# → [{"identifier": "DIPUTACIO-DE-BARCELONA", ...}]

# Pas 2: obtenir perfil complet
menjometre entity DIPUTACIO-DE-BARCELONA --json
# → Llegir `total_public_funds` per l'import total
# → Llegir `total_amount` per només subvencions
# → Llegir `total_contract_amount` per només contractes

Flux 2: "Quines són les entitats més subvencionades?"

menjometre top --limit 20 --sort amount --json
# → Array de 20 entitats ordenades per `total_public_funds` descendent

Flux 3: "Què es podria pagar amb X euros?"

menjometre equivalencies 54000000 --json
# → Llista d'equivalències (mestres, escoles, ambulàncies, etc.)

Flux 4: "Analitzar una entitat en profunditat"

# 1. Perfil + puntuació + equivalències
menjometre entity CRUZ-ROJA-ESPANOLA --json

# 2. Detall de subvencions per any
menjometre grants CRUZ-ROJA-ESPANOLA --year 2024 --json
menjometre grants CRUZ-ROJA-ESPANOLA --year 2023 --json

# 3. Detall de contractes
menjometre contracts CRUZ-ROJA-ESPANOLA --json

# 4. Context: quant és respecte el total?
menjometre stats --json
# → Comparar entity.total_public_funds amb stats.total_amount + stats.total_contract_amount

Flux 5: "Quins mitjans de comunicació reben més?"

menjometre top --type premsa --limit 50 --sort amount --json

Formats de sortida

| Flag | Format | Ús | |---|---|---| | (cap) | Taula formatejada amb colors | Lectura humana al terminal | | --json | JSON estructurat | Agents, scripts, pipelines | | --csv | CSV amb capçaleres | Fulls de càlcul, anàlisi de dades |

# Exportar ranking a CSV
menjometre top --limit 100 --csv > ranking.csv

Configuració

# Per defecte: producció
export MENJOMETRE_API_BASE=https://menjometre.cat

# Desenvolupament local
export MENJOMETRE_API_BASE=http://localhost:3000

No cal autenticació. L'API és pública amb CORS obert.

Gestió d'errors

| Codi HTTP | Significat | Acció recomanada | |---|---|---| | 400 | Paràmetre invàlid (ex: amount negatiu) | Revisar paràmetres | | 404 | Entitat no trobada | Provar search primer per verificar que existeix | | 500 | Error intern del servidor | Reintentar després d'uns segons |

Errors retornen: {"error": "missatge descriptiu"}

API REST directa

Si prefereixes HTTP en lloc de la CLI:

| Endpoint | Equivalent CLI | |---|---| | GET https://menjometre.cat/api/search?q=creu+roja | menjometre search "creu roja" --json | | GET https://menjometre.cat/api/entity/CRUZ-ROJA-ESPANOLA | menjometre entity CRUZ-ROJA-ESPANOLA --json | | GET https://menjometre.cat/api/top?limit=10&sort_by=score | menjometre top --json | | GET https://menjometre.cat/api/stats | menjometre stats --json | | GET https://menjometre.cat/api/equivalencies?amount=5000000 | menjometre equivalencies 5000000 --json | | GET https://menjometre.cat/api/export/entity?identifier=SLUG&type=grants | menjometre grants SLUG --json | | GET https://menjometre.cat/api/export/entity?identifier=SLUG&type=contracts | menjometre contracts SLUG --json |

Codi font

• CLI: https://github.com/segellfoscIA/menjometre-cli (AGPL-3.0)
• Web + API: https://github.com/segellfoscIA/menjometre (AGPL-3.0)