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/.
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")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)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:00ZGet 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 413Get 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:00ZPlease 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.