Saltar al contingut principal

Onomàstica. API RSS

Aquesta API dona accés a informació estadística de noms i cognoms de la població i noms dels nadons. L'Idescat difon aquesta informació a la secció Onomàstica.

La utilització d'aquest servei comporta l'acceptació de les condicions d'ús de les APIs de l'Idescat.

Resum
URI base https://api.idescat.cat/onomastica/v1/{subservei}/{operació}.{format}[?paràmetres]
Mètode HTTP GET
Formats de la resposta xml, json, php, txt
Versió 1.00 (06/05/2013)
Dreceres Petició, Resposta
Operacions dades, cerca, sug

1. Petició

1.1. Característiques bàsiques

Tota petició a l'API d'Onomàstica ha d'especificar obligatòriament el servei (onomastica), la versió, el subservei, l'operació i el format. Versió i operació i subserveis (quan n'hi ha) són característiques específiques de cada servei. A més dels formats de resposta generals de les APIs de l'Idescat, el servei d'Onomàstica suporta el format text en l'operació sug. Per a més informació, consulteu l'apartat Anatomia de les peticions a la documentació general de les APIs de l'Idescat.

1.1.1. Identificador del servei i versió i subserveis admesos

L'identificador d'aquest servei és onomastica.

https://api.idescat.cat/onomastica/v1/{…}

Admet tres subserveis:

  • noms: dades de noms de la població
  • cognoms: dades de cognoms de la població
  • nadons: dades de noms dels nadons

És obligatori especificar un subservei.

https://api.idescat.cat/onomastica/v1/nadons/{…}

1.1.2. Operacions

Aquest servei admet tres tipus d'operacions:

  • dades: Retorna estadístiques d'un determinat nom o cognom.
    https://api.idescat.cat/onomastica/v1/nadons/dades.{…}
  • cerca: Retorna resultats d'una cerca pel fragment de nom de la població o dels nadons o de cognom de la població.
    https://api.idescat.cat/onomastica/v1/noms/cerca.{…}
  • sug: Retorna la llista alfabètica de noms o cognoms que comencen pels caràcters especificats.
    https://api.idescat.cat/onomastica/v1/cognoms/sug.{…}

1.2. Paràmetres específics

Aquest servei suporta els paràmetres generals (idioma i codificació) de les APIs de l'Idescat.

Els paràmetres específics permeten escollir la informació que retornarà una determinada operació del servei. Es poden especificar com a paràmetres individuals o en un únic paràmetre p (forma compacta).

1.2.1. Operació dades

L'operació dades retorna estadístiques d'un determinat nom o cognom.

1.2.1.1. Filtre id

Aquest paràmetre obligatori serveix per especificar el nom (en el cas dels subserveis noms i nadons) o el cognom (en el cas del subservei cognoms) del qual es volen recuperar estadístiques.

Ex. 1: Informació estadística del darrer any disponible de dones nascudes amb el nom MARIA (40683)
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683
Ex. 2: Informació estadística del darrer any disponible d'homes nascuts amb el nom MARIA (39969)
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=39969

Per obtenir l'identificador d'un determinat nom o cognom es pot utilitzar l'operació cerca.

El paràmetre id també permet especificar el literal del nom o cognom (sense accents) tal com consta a l'estadística d'onomàstica. Cal advertir, però, que quan s'especifica un literal en el paràmetre id, aquest no es pot combinar amb cap altre més paràmetre.

Ex. 3: Informació estadística del darrer any disponible dels nadons amb nom MARIA
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=MARIA

Com MARIA pot ser nom de nen o de nena, la crida anterior contindrà les estadístiques per separat de cada sexe (40683, 39969).

1.2.1.2. Filtre geo

El filtre geo permet filtrar territorialment els resultats. Per seleccionar el lloc de residència tots els subserveis accepten els següents prefixos:

  • prov: província
  • at: àmbit del Pla territorial
  • com: comarca
Ex. 4: Informació estadística de les persones amb cognom GARCIA (285413) a la població de la comarca de l'Alt Camp (COM:01) del darrer any disponible
https://api.idescat.cat/onomastica/v1/cognoms/dades.xml?id=285413&geo=com:01
Ex. 5: Informació estadística de les dones amb nom MARIA (40683) a la població de les Comarques Gironines (AT:02) del darrer any disponible
https://api.idescat.cat/onomastica/v1/noms/dades.xml?id=40683&geo=at:02

Per conèixer els codis utilitzats en els diferents àmbits geogràfics podeu utilitzar el paràmetre class.

1.2.1.3. Filtre t

En tots els subserveis excepte cognoms, es pot utilitzar el paràmetre t per filtrar temporalment les estadístiques. En el cas del subservei nadons, aquest paràmetre indica l'any de naixement.

Ex. 6: Informació estadística de les dones nascudes el 2009 amb el nom MARIA (40683)
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&t=2009

Per conèixer els anys disponibles en aquest subservei podeu utilitzar el paràmetre class. Si no s'especifica t o té un valor incorrecte, el subservei nadons retorna les estadístiques del darrer any disponible.

En el cas dels subserveis noms i cognoms, sempre es retornen estadístiques del darrer Registre de població de Catalunya. En el cas de noms, però, es pot utilitzar el paràmetre t per filtrar la població per dècada de naixement.

Ex. 7: Informació estadística de les dones a la població nascudes entre 1990 i 1999 amb el nom MARIA (40683)
https://api.idescat.cat/onomastica/v1/noms/dades.xml?id=40683&t=1990-1999

Els subserveis que accepten el filtre t permeten combinar-lo amb el filtre geo.

Ex. 8: Informació estadística de les dones nascudes al Baix Llobregat (com:11) el 2005 amb el nom MARIA (40683)
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&t=2005&geo=com:11

Per conèixer els valors vàlids en els subserveis noms i cognoms podeu utilitzar el paràmetre class. Si no s'especifica t o té un valor incorrecte, aquests dos subserveis retornen estadístiques de tota la població del darrer any disponible.

1.2.1.4. Filtre nac

En el subservei noms, es pot utilitzar el paràmetre nac per filtrar les estadístiques per nacionalitat. Aquest paràmetre no es pot combinar amb altres filtres.

Ex. 9: Informació estadística de les dones amb el nom MARIA (40683) amb nacionalitat polonesa
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&nac=pl

El paràmetre nac utilitza els codis dels països de l'estàndard ISO 3166-1 alpha-2. També podeu utilitzar el paràmetre class per determinar els països que apareixen a l'estadística. Si no s'especifica nac o té un valor incorrecte, el subservei noms retorna estadístiques de tota la població del darrer any disponible.

1.2.1.5. Paràmetre class

El paràmetre class permet establir la variable d'encreuament dels resultats. Els criteris de classificació depenen de cada subservei i són:

  • prov: per províncies
  • at: per àmbits del Pla territorial
  • com: per comarques
  • nac: per nacionalitat (només disponible en el subservei noms)
  • t: en el cas de noms, per dècada de naixement; en el cas de nadons, per any de naixement. El subservei cognoms no suporta aquest valor.
Ex. 10: Informació estadística de les dones amb nom MARIA (40683) en el darrer any disponible per comarques
https://api.idescat.cat/onomastica/v1/noms/dades.xml?id=40683&class=com
Ex. 11: Informació estadística de les dones amb nom MARIA (40683) per any de naixement
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&class=t

El paràmetre class es pot combinar amb filtres.

Ex. 12: Informació estadística de les dones nascudes al Baix Llobregat (com:11) amb nom MARIA (40683) per any de naixement
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&class=t&geo=com:11

En cas de conflicte entre la variable classificatòria i els filtres (per exemple, class=t&t=2005), tenen prioritat els filtres i s'ignorarà class.

1.2.2. Operació cerca

L'operació cerca permet obtenir resultats ordenats d'una cerca per un fragment de nom o cognom. Si hi ha molts resultats, es retornen paginats i cal utilitzar el paràmetre posicio per obtenir les diferents pàgines de resultats.

1.2.2.1. Filtre q

Permet filtrar els resultats per un fragment de nom o de cognom. Si s'especifica q, els resultats es mostren ordenats per similitud (primer els noms o cognoms que coincideixen exactament amb la cerca; després, els noms o cognoms de més d'un mot que inclouen la paraula cercada; finalment, els noms o cognoms que contenen com a fragment el text cercat) i freqüència.

Ex. 13: Estadística dels primers noms que contenen MARIA ordenats per similitud i freqüència
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?q=maria

Si no s'especifica una cadena de cerca (q) ni cap criteri d'ordenació (orderby, desc), es retornen els resultats ordenats ascendentment per freqüència. Quan no s'especifica q, a més, no s'inclouen en els resultats els noms o cognoms amb una freqüència inferior a 4 (en el cas dels cognoms, només s'inclouen si la freqüència és igual o superior a 4 tant en el primer cognom com en el segon).

Ex. 14: Estadística dels cognoms de menor a major freqüència
https://api.idescat.cat/onomastica/v1/cognoms/cerca.xml
1.2.2.2. Filtre sim

Els resultats de l'operació cerca tenen associada una categoria de similitud amb la cadena q buscada. El paràmetre sim permet filtrar els resultats segons aquesta similitud:

  • 0: Només es retornen els noms o cognoms la denominació dels quals coincideix amb l'especificada a q.
  • 1: Només es retornen els noms o cognoms que contenen la cadena q especificada com a paraula (o expressió) i no estan inclosos a l'apartat anterior.
  • 2: Només es retornen els noms o cognoms que contenen la cadena q especificada com a fragment i no estan inclosos als apartats anteriors.

Aquests valors es poden concatenar separats per comes. Per defecte, sim és igual a 0, 1, 2.

Ex. 15: Estadística de nadons que es diuen exactament MARIA
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?q=maria&sim=0
Ex. 16: Estadística de nadons que es diuen exactament MARIA o tenen un nom compost amb aquest mot
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?q=maria&sim=0,1

El paràmetre sim és ignorat si no s'ha especificat q.

1.2.2.3. Paràmetres orderby i desc

Si s'ha especificat q, els resultats es mostren ordenats per proximitat (sim) amb la cerca efectuada i freqüència. Els paràmetres orderby i desc permeten determinar l'ordenació dels resultats quan no s'ha especificat q.

  • orderby
    • v: Els resultats s'ordenen per freqüència d'aparició del nom o cognom, i després alfabèticament en ordre ascendent.
    • nom: Els resultats s'ordenen alfabèticament segons el nom o cognom, i després de més a menys freqüència.
    • sex: En el cas dels subserveis noms i nadons, els resultats s'ordenen segons gènere (homes, dones), i després de més a menys freqüència.
  • desc
    • 0: Ordre ascendent del criteri principal establert per orderby. És el valor per defecte.
    • 1: Ordre descendent del criteri principal establert per orderby.

Es recomana passar sempre explícitament els paràmetres orderby i desc.

Ex. 17: Estadística de noms més freqüents dels nadons a Catalunya
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?orderby=v&desc=1
Ex. 18: Estadística de noms més freqüents de les nenes nascudes a Catalunya
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?orderby=sex&desc=1
Ex. 19: Estadística de cognoms en ordre alfabètic
https://api.idescat.cat/onomastica/v1/cognoms/cerca.xml?orderby=nom

Els paràmetres orderby i desc són ignorats si s'ha especificat q.

1.2.2.4. Paràmetre posicio

Com algunes cerques poden retornar un nombre molt elevat de resultats, la resposta no sempre els inclourà tots. El paràmetre posicio permet determinar quin és el primer resultat inclòs a la resposta. Per defecte, posicio és igual a zero (es retornen resultats començant pel primer).

Ex. 20: Estadística dels noms més freqüents de la població a partir d'aquell que ocupa la posició 26
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?orderby=v&desc=1&posicio=25
1.2.2.5. Filtre geo

L'operació cerca admet el paràmetre geo, que té el mateix significat i restriccions que en l'operació dades (vegeu l'apartat 1.2.1.2).

Ex. 21: Estadística més recent dels noms més freqüents de la població a l'Alt Camp (com:01)
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?orderby=v&desc=1&geo=com:01
Ex. 22: Estadística dels nadons de l'Alt Camp (com:01) que es diuen exactament Maria
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?q=maria&sim=0&geo=com:01
Ex. 23: Estadística dels cognoms més freqüents a l'Alt Camp (com:01)
https://api.idescat.cat/onomastica/v1/cognoms/cerca.xml?orderby=v&desc=1&geo=com:01
Ex. 24: Estadística dels cognoms més freqüents que contenen EZ com a fragment a l'Alt Camp (com:01)
https://api.idescat.cat/onomastica/v1/cognoms/cerca.xml?q=ez&sim=2&orderby=v&desc=1&geo=com:01
1.2.2.6. Filtre t

L'operació cerca admet el paràmetre t, que té el mateix significat i restriccions que en l'operació dades (vegeu l'apartat 1.2.1.3).

Ex. 25: Estadística dels noms més freqüents de la població nascuda a la dècada dels vuitanta
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?orderby=v&desc=1&t=1980-1989
Ex. 26: Estadística dels noms més freqüents de la població nascuda a la dècada dels vuitanta a l'Alt Camp (com:01)
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?orderby=v&desc=1&t=1980-1989&geo=com:01
Ex. 27: Estadística dels noms més freqüents dels nadons nascuts el 2010
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?orderby=v&desc=1&t=2010
Ex. 28: Estadística dels noms més freqüents dels nadons nascuts el 2010 a l'Alt Camp (com:01)
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?orderby=v&desc=1&t=2010&geo=com:01
1.2.2.7. Filtre nac

L'operació cerca admet el paràmetre nac, que té el mateix significat i restriccions que en l'operació dades (vegeu l'apartat 1.2.1.4).

Ex. 29: Estadística dels noms més freqüents de la població amb nacionalitat polonesa
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?orderby=v&desc=1&nac=pl
Ex. 30: Estadística de la població amb nacionalitat polonesa que es diu exactament ANNA
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?q=anna&sim=0&nac=pl

1.2.3. Operació sug

L'operació sug retorna la llista alfabètica de noms o cognoms disponibles a la base de dades que comencen pels caràcters especificats pel paràmetre requerit q. La seva presència a la llista no indica la seva aparició a l'estadística de l'any més recent disponible.

A més dels formats generals (XML, JSON, PHP serialitzat), aquesta operació suporta el format TXT.

1.2.3.1. Filtre q

Aquest paràmetre és obligatori i s'utilitza per especificar els primers caràcters d'un nom o cognom.

Ex. 31: Noms de la població que comencen per MART
https://api.idescat.cat/onomastica/v1/noms/sug.txt?q=mart

Per limitar la grandària de la resposta, es recomana especificar a q una cadena d'almenys tres caràcters.

1.3. Invocació sense operació

Per raons d'amigabilitat, aquesta API admet peticions amb una sintaxi que no requereix especificar operacions (vegeu, a la documentació general de les APIs de l'Idescat, l'apartat 1.4. Invocació sense operació).

  • Estadística del nom 40683 (MARIA dona) a la població de Catalunya en format XML
    https://api.idescat.cat/onomastica/v1/noms/40683.xml
  • Estadística del nom MARIA a la població de Catalunya en format JSON
    https://api.idescat.cat/onomastica/v1/noms/maria.json
  • Estadística del cognoms que contenen MART a la població de Catalunya en format JSON
    https://api.idescat.cat/onomastica/v1/cognoms.json?q=mart
  • Noms de nadó que comencen per MART en format TXT
    https://api.idescat.cat/onomastica/v1/nadons.txt?sug=mart

2. Resposta

Per conèixer els codis de resposta HTTP retornats i els formats suportats per qualsevol servei, consulteu l'apartat 2 de les APIs de l'Idescat.

Amb caràcter general, quan un valor no es pugui oferir per raons de secret estadístic s'indicarà amb un _.

2.1. Operació dades

Cada subservei disposa del seu propi contenidor (onomastica_noms, onomastica_cognoms, onomastica_nadons) i dels següents elements generals comuns:

  • c: concepte.
  • r: referència temporal.
  • geo: referència geogràfica.
  • s: font.
  • updated: data d'actualització.
  • l: enllaç amb una taula relacionada amb el lloc web de l'Idescat.
Ex. 32: Elements generals comuns de l'operació dades
<onomastica_noms version="1.00" lang="ca" o="dades" n="47" p="id=40683;class=nac">
   <c sex="f">MARIA</c>
   <r>2012</r>
   <geo id="09" scheme="ca">Catalunya</geo>
   <s>Idescat, a partir del Registre de població de Catalunya.</s>
   <updated>2012-11-13T11:00:00+00:00</updated>
   <l>https://www.idescat.cat/noms/?geo=4&id=40683</l>
   …
</onomastica_noms>

Els resultats s'inclouen en un element ff amb tantes fileres (f) com possibles valors. L'element c descriu la filera.

Ex. 33: Estadístiques de noms per nacionalitat
<onomastica_noms version="1.00" lang="ca" o="dades" n="47" p="id=40683;class=nac">
   …
   <ff>
      <f>
         <c id="es" scheme="nac">Espanya</c>
         …
      </f>
      <f>
         <c id="ro" scheme="nac">Romania</c>
         …
      </f>
      <f>
         <c id="ru" scheme="nac">Rússia</c>
         …
      </f>
      …
      <f>
         <c>Total</c>
         …
      </f>
   </ff>
</onomastica_noms>
Ex. 34: Estadístiques del nom MARIA
<onomastica_noms version="1.00" lang="ca" o="dades" n="2" p="id=MARIA">
   <c>MARIA</c>
   <r>2012</r>
   <geo id="09" scheme="ca">Catalunya</geo>
   <s>Idescat, a partir del Registre de població de Catalunya.</s>
   <updated>2012-11-13T11:00:00+00:00</updated>
   <ff>
      <f>
         <c id="40683" sex="f">MARIA</c>
         …
      </f>
      <f>
         <c id="39969" sex="m">MARIA</c>
         …
      </f>
   </ff>
</onomastica_noms>

Les dades s'inclouen en els següents elements:

  • rank:
    • total: posició en el rànquing de tots els noms, sense distinció de gènere.
    • sex: posició en el rànquing dels noms del mateix gènere.
  • pos1:
    • v: freqüència d'aparició del nom, o del cognom com a primer cognom.
    • w:
      • total: pes en tant per mil sobre el total de noms o primers cognoms.
      • sex: pes en tant per mil sobre el total de noms del mateix gènere.
  • pos2:
    • v: freqüència d'aparició del cognom com a segon cognom.
    • w:
      • total: pes en tant per mil sobre el total de noms o segons cognoms.

El subservei cognoms no inclou cap element sex. Els subserveis noms i nadons no inclouen l'element pos2.

2.2. Operació cerca

L'operació cerca utilitza per descriure els resultats l'estàndard Atom enriquit amb elements de l'estàndard OpenSearch.

Les entrades (entry), a més, són esteses amb l'element f, tal com es descriu a l'operació dades.

2.3. Operació sug

Per descriure els resultats, l'operació sug utilitza l'estàndard OpenSearch Suggestions, que especifica una resposta en format JSON. Aquesta mateixa estructura s'utilitza en la resposta en format PHP serialitzat.

La resposta en format XML inclou la mateixa informació estructurada d'acord amb l'estàndard XML Search Suggestions Format (a vegades anomenat OpenSearch SearchSuggest2).

Per conveniència, també s'ofereix la resposta en format text, amb els resultats separats per salts de línia.

2.4. Errors

Les APIs de l'Idescat utilitzen codis de resposta normalitzats per indicar si la petició ha tingut èxit o si ha fracassat.