Saltar al contenido principal

Onomástica. API RSS

Esta API da acceso a información estadística de nombres y apellidos de la población y nombres de los recién nacidos. El Idescat difunde dicha información en la sección Onomástica.

La utilización de este servicio comporta la aceptación de las condiciones de uso de las API del Idescat.

Resumen
URI base https://api.idescat.cat/onomastica/v1/{subservicio}/{operación}.{formato}[?parámetros]
Método HTTP GET
Formatos de la respuesta xml, json, php, txt
Versión 1.00 (06/05/2013)
Atajos Petición, Respuesta
Operaciones dades, cerca, sug

1. Petición

1.1. Características básicas

Toda petición al API de Onomástica debe especificar obligatoriamente el servicio (onomastica), la versión, el subservicio, la operación y el formato. Versión y operación y subservicios (cuando existan) son características específicas de cada servicio. Además de los formatos de respuesta generales de las API del Idescat, el servicio de Onomástica soporta el formato texto en la operación sug. Para más información, consulte el apartado Anatomía de las peticiones en la documentación general de las API del Idescat.

1.1.1. Identificador del servicio y versión y subservicios admitidos

El identificador de este servicio es onomastica.

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

Admite tres subservicios:

  • noms: datos de nombres de la población
  • cognoms: datos de apellidos de la población
  • nadons: datos de nombres de los recién nacidos

Es obligatorio especificar un subservicio.

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

1.1.2. Operaciones

Este servicio admite tres tipos de operaciones:

  • dades: Devuelve estadísticas de un determinado nombre o apellido.
    https://api.idescat.cat/onomastica/v1/nadons/dades.{…}
  • cerca: Devuelve resultados de una búsqueda por el fragmento de nombre de la población o de los recién nacidos o de apellido de la población.
    https://api.idescat.cat/onomastica/v1/noms/cerca.{…}
  • sug: Devuelve la lista alfabética de nombres o apellidos que empiezan por los caracteres especificados.
    https://api.idescat.cat/onomastica/v1/cognoms/sug.{…}

1.2. Parámetros específicos

Este servicio soporta los parámetros generales (idioma y codificación) de las API del Idescat.

Los parámetros específicos permiten escoger la información que devolverá una determinada operación del servicio. Se pueden especificar como parámetros individuales o en un único parámetro p (forma compacta).

1.2.1. Operación dades

La operación dades devuelve estadísticas de un determinado nombre o apellido.

1.2.1.1. Filtro id

Este parámetro obligatorio sirve para especificar el nombre (en el caso de los subservicios noms y nadons) o el apellido (en el caso del subservicio cognoms) del que se quieren recuperar estadísticas.

Ej. 1: Información estadística del último año disponible de mujeres nacidas con el nombre MARIA (40683)
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&lang=es
Ej. 2: Información estadística del último año disponible de hombres nacidos con el nombre MARIA (39969)
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=39969&lang=es

Para obtener el identificador de un determinado nombre o apellido se puede utilizar la operación cerca.

El parámetro id también permite especificar el literal del nombre o apellido (sin acentos) tal como consta en la estadística de onomástica. Hay que advertir, sin embargo, que cuando se especifica un literal en el parámetro id, este no se puede combinar con ningún otro parámetro más.

Ej. 3: Información estadística del último año disponible de los recién nacidos con nombre MARIA
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=MARIA&lang=es

Como MARIA puede ser nombre de niño o de niña, la petición anterior contendrá las estadísticas por separado de cada sexo (40683, 39969).

1.2.1.2. Filtro geo

El filtro geo permite filtrar territorialmente los resultados. Para seleccionar el lugar de residencia todos los subservicios aceptan los siguientes prefijos:

  • prov: provincia
  • at: ámbito del Plan territorial
  • com: comarca
Ej. 4: Información estadística de las personas con apellido GARCIA (285413) en la población de la comarca del Alt Camp (COM:01) del último año disponible
https://api.idescat.cat/onomastica/v1/cognoms/dades.xml?id=285413&geo=com:01&lang=es
Ej. 5: Información estadística de las mujeres con nombre MARIA (40683) en la población de las Comarques Gironines (AT:02) del último año disponible
https://api.idescat.cat/onomastica/v1/noms/dades.xml?id=40683&geo=at:02&lang=es

Para conocer los códigos utilizados en los diferentes ámbitos geográficos puede utilizar el parámetro class.

1.2.1.3. Filtro t

En todos los subservicios, excepto cognoms, se puede utilizar el parámetro t para filtrar temporalmente las estadísticas. En el caso del subservicio nadons, este parámetro indica el año de nacimiento.

Ej. 6: Información estadística de las mujeres nacidas en el 2009 con el nombre MARIA (40683)
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&t=2009&lang=es

Para conocer los años disponibles en este subservicio puede utilizar el parámetro class. Si no se especifica t o tiene un valor incorrecto, el subservicio nadons devuelve las estadísticas del último año disponible.

En el caso de los subservicios noms y cognoms, siempre se devuelven estadísticas del último Registro de población de Cataluña. En el caso de noms, sin embargo, se puede utilizar el parámetro t para filtrar la población por década de nacimiento.

Ej. 7: Información estadística de las mujeres en la población nacidas entre 1990 y 1999 con el nombre MARIA (40683)
https://api.idescat.cat/onomastica/v1/noms/dades.xml?id=40683&t=1990-1999&lang=es

Los subservicios que aceptan el filtro t permiten combinarlo con el filtro geo.

Ej. 8: Información estadística de las mujeres nacidas en el Baix Llobregat (com:11) en el 2005 con el nombre MARIA (40683)
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&t=2005&geo=com:11&lang=es

Para conocer los valores válidos en los subservicios noms y cognoms puede utilizar el parámetro class. Si no se especifica t o tiene un valor incorrecto, estos dos subservicios devuelven estadísticas de toda la población del último año disponible.

1.2.1.4. Filtro nac

En el subservicio noms, se puede utilizar el parámetro nac para filtrar las estadísticas por nacionalidad. Este parámetro no se puede combinar con otros filtros.

Ej. 9: Información estadística de las mujeres con el nombre MARIA (40683) con nacionalidad polaca
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&nac=pl&lang=es

El parámetro nac utiliza los códigos de los países del estándar ISO 3166-1 alpha-2. También puede utilizar el parámetro class para determinar los países que aparecen en la estadística. Si no se especifica nac o tiene un valor incorrecto, el subservicio noms devuelve estadísticas de toda la población del último año disponible.

1.2.1.5. Parámetro class

El parámetro class permite establecer la variable de cruce de los resultados. Los criterios de clasificación dependen de cada subservicio y son:

  • prov: por provincias
  • at: por ámbitos del Plan territorial
  • com: por comarcas
  • nac: por nacionalidad (sólo disponible en el subservicio noms)
  • t: en el caso de noms, por década de nacimiento; en el caso de nadons, por año de nacimiento. El subservicio cognoms no soporta este valor.
Ej. 10: Información estadística de las mujeres con nombre MARIA (40683) en el último año disponible por comarcas
https://api.idescat.cat/onomastica/v1/noms/dades.xml?id=40683&class=com&lang=es
Ej. 11: Información estadística de las mujeres con nombre MARIA (40683) por año de nacimiento
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&class=t&lang=es

El parámetro class se puede combinar con filtros.

Ej. 12: Información estadística de las mujeres nacidas en el Baix Llobregat (com:11) con nombre MARIA (40683) por año de nacimiento
https://api.idescat.cat/onomastica/v1/nadons/dades.xml?id=40683&class=t&geo=com:11&lang=es

En caso de conflicto entre la variable clasificatoria y los filtros (per exemple, class=t&t=2005), tienen prioridad los filtros y se ignorará class.

1.2.2. Operación cerca

La operación cerca permite obtener resultados ordenados de una búsqueda por un fragmento de nombre o apellido. Si hay muchos resultados, se devuelven paginados y es necesario utilizar el parámetro posicio para obtener las diferentes páginas de resultados.

1.2.2.1. Filtro q

Permite filtrar los resultados por un fragmento de nombre o de apellido. Si se especifica q, los resultados se muestran ordenados por similitud (primero los nombres o apellidos que coinciden exactamente con la búsqueda; después, los nombres o apellidos de más de una palabra que incluyen la palabra búsqueda; por último, los nombres o apellidos que contienen como fragmento el texto buscado) y frecuencia.

Ej. 13: Estadística de los primeros nombres que contienen MARIA ordenados por similitud y frecuencia
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?q=maria&lang=es

Si no se especifica ninguna cadena de búsqueda (q) ni ningún criterio de ordenación (orderby, desc), se devuelven los resultados ordenados ascendentemente por frecuencia. Además, cuando no se especifica q, no se incluyen en los resultados los nombres o apellidos con una frecuencia inferior a 4 (en el caso de los apellidos, solamente se incluyen si la frecuencia es igual o superior a 4 tanto en el primer apellido como en el segundo).

Ej. 14: Estadística de los apellidos de menor a mayor frecuencia
https://api.idescat.cat/onomastica/v1/cognoms/cerca.xml?lang=es
1.2.2.2. Filtro sim

Los resultados de la operación cerca tienen asociada una categoría de similitud con la cadena q buscada. El parámetro sim permite filtrar los resultados según esta similitud:

  • 0: Solamente se devuelven los nombres o apellidos cuya denominación coincide con la especificada en q.
  • 1: Solamente se devuelven los nombres o apellidos que contienen la cadena q especificada como palabra (o expresión) y no están incluidos en el apartado anterior.
  • 2: Solamente se devuelven los nombres o apellidos que contienen la cadena q especificada como fragmento y no están incluidos en los apartados anteriores.

Estos valores se pueden concatenar separados por comas. Por defecto, sim es igual a 0, 1, 2.

Ej. 15: Estadística de recién nacidos que se llaman exactamente MARIA
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?q=maria&sim=0&lang=es
Ej. 16: Estadística de recién nacidos que se llaman exactamente MARIA o tienen un nombre compuesto con esta palabra
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?q=maria&sim=0,1&lang=es

El parámetro sim es ignorado si no se ha especificado q.

1.2.2.3. Parámetros orderby y desc

Si se ha especificado q, los resultados se muestran ordenados por proximidad (sim) con la búsqueda efectuada y frecuencia. Los parámetros orderby y desc permiten determinar la ordenación de los resultados cuando no se ha especificado q.

  • orderby
    • v: Los resultados se ordenan por frecuencia de aparición del nombre o apellido, y después alfabéticamente en orden ascendente.
    • nom: Los resultados se ordenan alfabéticamente según el nombre o apellido, y después de más a menos frecuencia.
    • sex: En el caso de los subservicios noms y nadons, los resultados se ordenan según sexo (hombres, mujeres), y después de más a menos frecuencia
  • desc
    • 0: Orden ascendente del principal criterio establecido por orderby. Es el valor por defecto.
    • 1: Orden descendente del principal criterio establecido por orderby.

Se recomienda pasar siempre explícitamente los parámetros orderby y desc.

Ej. 17: Estadística de nombres más frecuentes de los recién nacidos en Cataluña
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?orderby=v&desc=1&lang=es
Ej. 18: Estadística de nombres más frecuentes de las niñas nacidas en Cataluña
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?orderby=sex&desc=1&lang=es
Ej. 19: Estadística de apellidos en orden alfabético
https://api.idescat.cat/onomastica/v1/cognoms/cerca.xml?orderby=nom&lang=es

Los parámetros orderby y desc son ignorados si se ha especificado q.

1.2.2.4. Parámetro posicio

Como algunas búsquedas pueden devolver un número muy elevado de resultados, la respuesta no siempre los incluirá a todos. El parámetro posicio permite determinar cuál es el primer resultado incluido en la respuesta. Por defecto, posicio es igual a cero (se devuelven resultados empezando por el primero).

Ej. 20: Estadística de los nombres más frecuentes de la población a partir del que ocupa la posición 26
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?orderby=v&desc=1&posicio=25&lang=es
1.2.2.5. Filtro geo

La operación cerca admite el parámetro geo, que tiene el mismo significado y restricciones que en la operación dades (ver el apartado 1.2.1.2).

Ej. 21: Estadística más reciente de los nombres más frecuentes de la población en el Alt Camp (com:01)
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?orderby=v&desc=1&geo=com:01&lang=es
Ej. 22: Estadística de los recién nacidos del Alt Camp (com:01) que se llaman exactamente Maria
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?q=maria&sim=0&geo=com:01&lang=es
Ej. 23: Estadística de los apellidos más frecuentes en el Alt Camp (com:01)
https://api.idescat.cat/onomastica/v1/cognoms/cerca.xml?orderby=v&desc=1&geo=com:01&lang=es
Ej. 24: Estadística de los apellidos más frecuentes que contienen EZ como fragmento en el Alt Camp (com:01)
https://api.idescat.cat/onomastica/v1/cognoms/cerca.xml?q=ez&sim=2&orderby=v&desc=1&geo=com:01&lang=es
1.2.2.6. Filtro t

La operación cerca admite el parámetro t, que tiene el mismo significado y restricciones que en la operación dades (ver el apartado 1.2.1.3).

Ej. 25: Estadística de los nombres más frecuentes de la población nacida en la década de los ochenta
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?orderby=v&desc=1&t=1980-1989&lang=es
Ej. 26: Estadística de los nombres más frecuentes de la población nacida en la década de los ochenta en el Alt Camp (com:01)
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?orderby=v&desc=1&t=1980-1989&geo=com:01&lang=es
Ej. 27: Estadística de los nombres más frecuentes de los recién nacidos en el 2010
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?orderby=v&desc=1&t=2010&lang=es
Ej. 28: Estadística de los nombres más frecuentes de los recién nacidos en el 2010 en el Alt Camp (com:01)
https://api.idescat.cat/onomastica/v1/nadons/cerca.xml?orderby=v&desc=1&t=2010&geo=com:01&lang=es
1.2.2.7. Filtro nac

La operación cerca admite el parámetro nac, que tiene el mismo significado y restricciones que en la operación dades (ver el apartado 1.2.1.4).

Ej. 29: Estadística de los nombres más frecuentes de la población con nacionalidad polaca
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?orderby=v&desc=1&nac=pl&lang=es
Ej. 30: Estadística de la población con nacionalidad polaca que se llama exactamente ANNA
https://api.idescat.cat/onomastica/v1/noms/cerca.xml?q=anna&sim=0&nac=pl&lang=es

1.2.3. Operación sug

La operación sug devuelve la lista alfabética de nombres o apellidos disponibles en la base de datos que comienzan por los caracteres especificados por el parámetro requerido q. Su presencia en la lista no indica su aparición en la estadística del año más reciente disponible.

Además de los formatos generales (XML, JSON, PHP serializado), dicha operación soporta el formato TXT.

1.2.3.1. Filtro q

Este parámetro es obligatorio y se utiliza para especificar los primeros caracteres de un nombre o apellido.

Ej. 31: Nombres de la población que empiezan por MART
https://api.idescat.cat/onomastica/v1/noms/sug.txt?q=mart&lang=es

Para limitar el tamaño de la respuesta, se recomienda especificar una cadena de al menos tres caracteres.

1.3. Invocación sin operación

Por motivos de amigabilidad, esta API admite peticiones con una sintaxis que no requiere especificar operaciones (ver, en la documentación general de las API del Idescat, el apartado 1.4. Invocación sin operación).

  • Estadística del nombre 40683 (MARIA mujer) en la población de Cataluña en formato XML
    https://api.idescat.cat/onomastica/v1/noms/40683.xml?lang=es
  • Estadística del nombre MARIA en la población de Cataluña en formato JSON
    https://api.idescat.cat/onomastica/v1/noms/maria.json?lang=es
  • Estadística de los apellidos que contienen MART en la población de Cataluña en formato JSON
    https://api.idescat.cat/onomastica/v1/cognoms.json?q=mart&lang=es
  • Nombres de recién nacido que empiezan por MART en formato TXT
    https://api.idescat.cat/onomastica/v1/nadons.txt?sug=mart&lang=es

2. Respuesta

Para conocer los códigos de respuesta HTTP devueltos y los formatos soportados por cualquier servicio, consulte el apartado 2 de las API del Idescat.

Con carácter general, cuando un valor no pueda ser ofrecido por razones de secreto estadístico se indicará con un _.

2.1. Operación dades

Cada subservicio dispone de su propio contenedor (onomastica_noms, onomastica_cognoms, onomastica_nadons) y de los siguientes elementos generales comunes:

  • c: concepto.
  • r: referencia temporal.
  • geo: referencia geográfica.
  • s: fuente.
  • updated: fecha de actualización.
  • l: enlace con una tabla relacionada con el sitio web del Idescat.
Ej. 32: Elementos generales comunes de la operación dades
<onomastica_noms version="1.00" lang="es" 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 Registro de población de Cataluña.</s>
   <updated>2012-11-13T11:00:00+00:00</updated>
   <l>https://www.idescat.cat/noms/?geo=4&id=40683&lang=es</l>
   …
</onomastica_noms>

Los resultados se incluyen en un elemento ff con tantas filas (f) como posibles valores. El elemento c describe la fila.

Ej. 33: Estadísticas de nombres por nacionalidad
<onomastica_noms version="1.00" lang="es" o="dades" n="47" p="id=40683;class=nac">
   …
   <ff>
      <f>
         <c id="es" scheme="nac">España</c>
         …
      </f>
      <f>
         <c id="ro" scheme="nac">Rumania</c>
         …
      </f>
      <f>
         <c id="ru" scheme="nac">Rusia</c>
         …
      </f>
      …
      <f>
         <c>Total</c>
         …
      </f>
   </ff>
</onomastica_noms>
Ej. 34: Estadísticas del nombre MARIA
<onomastica_noms version="1.00" lang="es" 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 Registro de población de Cataluña.</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>

Los datos se incluyen en los siguientes elementos:

  • rank:
    • total: posición en el ranking de todos los nombres, sin distinción de sexo.
    • sex: posición en el ranking de los nombres del mismo sexo.
  • pos1:
    • v: frecuencia de aparición del nombre o del apellido como primer apellido.
    • w:
      • total: peso en tanto por mil sobre el total de nombres o primeros apellidos.
      • sex: peso en tanto por mil sobre el total de nombres del mismo sexo.
  • pos2:
    • v: frecuencia de aparición del apellido como segundo apellido.
    • w:
      • total: peso en tanto por mil sobre el total de nombres o segundos apellidos.

El subservicio cognoms no incluye ningún elemento sex. Los subservicios noms y nadons no incluyen el elemento pos2.

2.2. Operación cerca

La operación cerca utiliza para describir los resultados el estándar Atom enriquecido con elementos del estándar OpenSearch.

Las entradas (entry), además, son extendidas con el elemento f, tal como se describe en la operación dades.

2.3. Operación sug

Para describir los resultados, la operación sug utiliza el estándar OpenSearch Suggestions, que especifica una respuesta en formato JSON. Esta misma estructura se utiliza en la respuesta en formato PHP serializado.

La respuesta en formato XML incluye la misma información estructurada de acuerdo con el estándar XML Search Suggestions Format (en ocasiones llamado OpenSearch SearchSuggest2).

Por conveniencia, también se ofrece la respuesta en formato texto, con los resultados separados por saltos de línea.

2.4. Errores

Las API del Idescat utilizan códigos de respuesta normalizados para indicar si la petición ha tenido éxito o si ha fracasado.