Interface to the HAL Open Archive API

An interface to the search API of 'HAL' < https://hal.science/>, the French open archive for scholarly documents from all academic fields. This package provides programmatic access to the API < https://api.archives-ouvertes.fr/docs> and allows to search for records and download documents.

odyssey

An interface to the search API of HAL, the French open archive for scholarly documents from all academic fields. This package provides programmatic access to the API and allows to search for records and download documents.

To cite odyssey in publications use:

Frerebeau N (2026). odyssey: Interface to the HAL Open Archive API. Université Bordeaux Montaigne, Pessac, France. doi:10.5281/zenodo.18195982 https://doi.org/10.5281/zenodo.18195982. R package version 1.0.1, https://nfrerebeau.codeberg.page/odyssey/.

Installation

You can install the released version of odyssey from CRAN with:

install.packages("odyssey")

And the development version from Codeberg with:

# install.packages("remotes")
remotes::install_git("https://codeberg.org/nfrerebeau/odyssey")

Usage

The use of odyssey involves three steps. First, a default query is created using hal_query(). Then, a set of functions allows to customize this query (see below). Finally, hal_search() and hal_download() allow to collect data and to download documents. as.data.frame() can be used to (try to) coerce the results of hal_search() to a data.frame.

The following functions allow you to customize a query. They must be applied to the object returned by hal_query() and can be called in any order. See the HAL search API documentation for a list of available fields.

• hal_query() allows to choose the fields to query and to define the query terms using boolean logic (q parameter).
• hal_select() is used to select the fields to be returned in the results (fl parameter).
• hal_filter() is used to retain all results that satisfy a conditions (fq parameter). hal_filter() can be used several times to add multiple search filters.
• hal_sort() orders the results by the value of the select field (sort parameter). According to the HAL API documentation, you should avoid text fields and multi-valued fields which will produce unpredictable results.
• hal_group() is used to group search results (group.* parameters).
• hal_facet() is used to facet search results (facet.* parameters).

For a simple search, grouping terms in a list allows to combine them with AND, while grouping terms in a vector allows to combine all the terms with OR. If needed, the infix functions %AND%, %OR%, %NOT%, %IN%, %TO% allow to build more complex queries (remember that infix operators are composed left to right).

## Load packages
library(odyssey)

Simple search

Get the 10 most recent articles about archaeology of Celts in France:

## Topic selection
## Will be combined with AND
topic <- list("archéologie", "Celtes", "France")

## Search publications with DOI
resp <- hal_query(topic) |>
  hal_select("doiId_s", "producedDate_tdate") |>
  hal_filter("" %TO% "" %IN% "doiId_s") |>
  hal_sort("producedDate_tdate", decreasing = TRUE) |>
  hal_search(limit = 10)

as.data.frame(resp)
#>                                          doiId_s   producedDate_tdate
#> 1  10.70675/f99b5e04z37e1z4dd5z8b41ze02da4b19bc7 2022-10-27T00:00:00Z
#> 2                       10.4000/books.pcjb.8230. 2021-08-01T00:00:00Z
#> 3                        10.4000/books.pcjb.8397 2021-01-01T00:00:00Z
#> 4                          10.4000/anabases.9669 2019-10-21T00:00:00Z
#> 5                            10.26406/STETR81-08 2019-01-01T00:00:00Z
#> 6                     10.4000/books.artehis.3178 2017-10-01T00:00:00Z
#> 7                     10.4000/books.artehis.3265 2017-10-01T00:00:00Z
#> 8                    10.4000/archeosciences.4457 2015-01-01T00:00:00Z
#> 9                        10.3406/galia.2007.3311 2007-01-01T00:00:00Z
#> 10                       10.3406/galia.2004.3184 2004-01-01T00:00:00Z

Faceting

Get the number of documents in archaeology by journal:

resp <- hal_query("shs.archeo", field = "domainAllCode_s") |>
  hal_facet(field = "journalTitle_s", limit = 10) |>
  hal_search()

as.data.frame(resp)
#> $journalTitle_s
#>                                                                    .value
#> 1        Bulletin de l'Association française pour l'étude de l'âge du Fer
#> 2  Gallia - Fouilles et monuments archéologiques en France métropolitaine
#> 3                          Bulletin de la Société préhistorique française
#> 4                                                   Archéologie médiévale
#> 5                                   Cahier des thèmes transversaux ArScAn
#> 6                              Journal of Archaeological Science: Reports
#> 7                                                Quaternary International
#> 8                                                             Archéologia
#> 9                                                  Dossiers d'Archéologie
#> 10                                         Les Nouvelles de l'archéologie
#>    .counts
#> 1      720
#> 2      671
#> 3      665
#> 4      537
#> 5      535
#> 6      435
#> 7      432
#> 8      424
#> 9      419
#> 10     413

Group Results

Get the first 20 documents in the ARCHEOSCIENCES-BORDEAUX collection, sorted by publication date in descending order, grouped by document type:

resp <- hal_query() |>
  hal_filter("ARCHEOSCIENCES-BORDEAUX" %IN% "collCode_s") |> 
  hal_select("producedDate_tdate", "docid") |>
  hal_group(field = "docType_s", limit = 20) |> 
  hal_sort("producedDate_tdate", decreasing = TRUE) |>
  hal_search()

head(as.data.frame(resp))
#>   .group   docid   producedDate_tdate
#> 1 POSTER 5385915 2024-11-06T00:00:00Z
#> 2 POSTER 4672790 2024-06-03T00:00:00Z
#> 3 POSTER 5573033 2023-05-19T00:00:00Z
#> 4 POSTER 5033934 2025-03-24T00:00:00Z
#> 5 POSTER 5449984 2025-09-10T00:00:00Z
#> 6 POSTER 5599153 2022-05-16T00:00:00Z

Code of Conduct

Please note that the odyssey project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.