Skip to content

bulletin.eurlex

EUR-Lex support is split into two layers:

Basic Imports

from bulletin.eurlex.api.client import EurlexBulletinClient
from bulletin.eurlex.api.models import EurlexOfficialAct

Client

bulletin.eurlex.api.client.EurlexBulletinClient

Client to query EU Official Journal acts.

Source code in src/bulletin/eurlex/api/client.py 
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
class EurlexBulletinClient:
    """Client to query EU Official Journal acts."""

    def __init__(self, endpoint: str = SPARQL_ENDPOINT, timeout: int = 300):
        self._connector = EurlexConnector(endpoint=endpoint, timeout=timeout)

    def get_acts(
        self,
        date: str,
        language: str = DEFAULT_LANGUAGE,
        date_end: Optional[str] = None,
        title_contains: Optional[str] = None,
        category_type: Optional[str] = None,
        institution_type: Optional[str] = None,
        output_format: Optional[str] = None,
    ) -> _ActsOutput:
        """Fetch Official Journal acts for a given publication date.

        Args:
            date: Publication date in ISO format (e.g. "2025-03-27").
            language: ISO Language code (default: "ENG"). Supported values are defined in `LANGUAGE_CODE_MAP`. Examples: "ENG", "FRA", "DEU", "SPA"...
            date_end: End date in ISO format (e.g. "2025-03-27"). If provided, fetch acts published between `date` and `date_end` inclusive.
            title_contains: Case-insensitive substring filter on title.
            category_type: Filter by category type code (e.g. "RES" for Resolution, "ANNOUNC" for Announcement...). More types available at <http://publications.europa.eu/resource/authority/resource-type>. Optional.
            institution_type: Filter by institution type code (e.g. "CONSIL" for Council of the European Union, "COM" for Commission...). More types available at <http://publications.europa.eu/resource/authority/corporate-body>. Optional.
            output_format: Optional output format. Use None or "objects" to return a list of `EurlexOfficialAct` objects, "json" to return a JSON-compatible list of dictionaries, "csv" to return CSV text, "xml" to return XML text, or "df" to return a pandas DataFrame.
        Returns:
            Acts in the requested output format.

        """
        normalized_output_format = _normalize_acts_output_format(output_format)
        query = self._connector.build_acts_query(
            date,
            language=language,
            date_end=date_end,
            title_contains=title_contains,
            category_type=category_type,
            institution_type=institution_type,
        )
        response = self._connector.execute_query(query)
        acts = parse_acts_results(response)
        return _format_acts(acts, normalized_output_format)

    def get_act_content(
        self,
        act_id_or_uri: str,
        language: str = DEFAULT_LANGUAGE,
        max_size: Optional[int] = None,
        return_bytes: bool = False,
    ) -> Union[str, bytes]:
        """Fetch the publication content stream for an act.

        Pass either a CELEX id (for example "52025M12135") or the full URI
        returned by `EurlexOfficialAct.celex_uri`.

        Args:
            act_id_or_uri: CELEX id or full resource CELLEX URI. This is not the
                Official Journal act number.
            language: ISO 639-3 language code (default: "ENG").
            max_size: Optional maximum content-stream size in bytes.
            return_bytes: Return raw response bytes instead of decoded text.

        Returns:
            The publication content decoded as html text, or bytes when return_bytes
            is True.
        """
        resource_uri = self._connector.build_act_content_url(act_id_or_uri)
        return self._connector.fetch_publication_content(
            resource_uri,
            language=language,
            max_size=max_size,
            return_bytes=return_bytes,
        )

    def get_category_types(
        self, language: str = DEFAULT_LANGUAGE, search: Optional[str] = None
    ) -> list[CategoryType]:
        """Fetch the list of possible category types from the authority list. This method may last a few minutes due to the size of the authority list.

        Args:
            language: Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...
            search: Optional case-insensitive substring filter on category type labels.

        Returns:
            A list of CategoryType objects with 'code' and 'label' attributes.
        """
        query = self._connector.build_category_types_query(language=language, search=search)
        response = self._connector.execute_query(query)
        return parse_category_types_results(response)

    def get_institution_types(
        self, language: str = DEFAULT_LANGUAGE, search: Optional[str] = None
    ) -> list[InstitutionType]:
        """Fetch the list of possible institution types from the authority list. This method may last a few minutes due to the size of the authority list.

        Args:
            language: Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...
            search: Optional case-insensitive substring filter on the label.

        Returns:
            A list of InstitutionType objects with 'code' and 'label' attributes.
        """
        query = self._connector.build_institution_types_query(language=language, search=search)
        response = self._connector.execute_query(query)
        return parse_institution_types_results(response)

get_act_content(act_id_or_uri, language=DEFAULT_LANGUAGE, max_size=None, return_bytes=False)

Fetch the publication content stream for an act.

Pass either a CELEX id (for example "52025M12135") or the full URI returned by EurlexOfficialAct.celex_uri.

Parameters:

Name Type Description Default
act_id_or_uri str

CELEX id or full resource CELLEX URI. This is not the Official Journal act number.

 required
language str

ISO 639-3 language code (default: "ENG").

 DEFAULT_LANGUAGE
max_size Optional[int]

Optional maximum content-stream size in bytes.

 None
return_bytes bool

Return raw response bytes instead of decoded text.

 False

Returns:

Type Description
Union[str, bytes]

The publication content decoded as html text, or bytes when return_bytes
Union[str, bytes]

is True.
Source code in src/bulletin/eurlex/api/client.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def get_act_content(
    self,
    act_id_or_uri: str,
    language: str = DEFAULT_LANGUAGE,
    max_size: Optional[int] = None,
    return_bytes: bool = False,
) -> Union[str, bytes]:
    """Fetch the publication content stream for an act.

    Pass either a CELEX id (for example "52025M12135") or the full URI
    returned by `EurlexOfficialAct.celex_uri`.

    Args:
        act_id_or_uri: CELEX id or full resource CELLEX URI. This is not the
            Official Journal act number.
        language: ISO 639-3 language code (default: "ENG").
        max_size: Optional maximum content-stream size in bytes.
        return_bytes: Return raw response bytes instead of decoded text.

    Returns:
        The publication content decoded as html text, or bytes when return_bytes
        is True.
    """
    resource_uri = self._connector.build_act_content_url(act_id_or_uri)
    return self._connector.fetch_publication_content(
        resource_uri,
        language=language,
        max_size=max_size,
        return_bytes=return_bytes,
    )

get_acts(date, language=DEFAULT_LANGUAGE, date_end=None, title_contains=None, category_type=None, institution_type=None, output_format=None)

Fetch Official Journal acts for a given publication date.

Parameters:

Name Type Description Default
date str

Publication date in ISO format (e.g. "2025-03-27").

 required
language str

ISO Language code (default: "ENG"). Supported values are defined in LANGUAGE_CODE_MAP. Examples: "ENG", "FRA", "DEU", "SPA"...

 DEFAULT_LANGUAGE
date_end Optional[str]

End date in ISO format (e.g. "2025-03-27"). If provided, fetch acts published between date and date_end inclusive.

 None
title_contains Optional[str]

Case-insensitive substring filter on title.

 None
category_type Optional[str]

Filter by category type code (e.g. "RES" for Resolution, "ANNOUNC" for Announcement...). More types available at http://publications.europa.eu/resource/authority/resource-type. Optional.

 None
institution_type Optional[str]

Filter by institution type code (e.g. "CONSIL" for Council of the European Union, "COM" for Commission...). More types available at http://publications.europa.eu/resource/authority/corporate-body. Optional.

 None
output_format Optional[str]

Optional output format. Use None or "objects" to return a list of EurlexOfficialAct objects, "json" to return a JSON-compatible list of dictionaries, "csv" to return CSV text, "xml" to return XML text, or "df" to return a pandas DataFrame.

 None

Returns: Acts in the requested output format.

Source code in src/bulletin/eurlex/api/client.py 
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def get_acts(
    self,
    date: str,
    language: str = DEFAULT_LANGUAGE,
    date_end: Optional[str] = None,
    title_contains: Optional[str] = None,
    category_type: Optional[str] = None,
    institution_type: Optional[str] = None,
    output_format: Optional[str] = None,
) -> _ActsOutput:
    """Fetch Official Journal acts for a given publication date.

    Args:
        date: Publication date in ISO format (e.g. "2025-03-27").
        language: ISO Language code (default: "ENG"). Supported values are defined in `LANGUAGE_CODE_MAP`. Examples: "ENG", "FRA", "DEU", "SPA"...
        date_end: End date in ISO format (e.g. "2025-03-27"). If provided, fetch acts published between `date` and `date_end` inclusive.
        title_contains: Case-insensitive substring filter on title.
        category_type: Filter by category type code (e.g. "RES" for Resolution, "ANNOUNC" for Announcement...). More types available at <http://publications.europa.eu/resource/authority/resource-type>. Optional.
        institution_type: Filter by institution type code (e.g. "CONSIL" for Council of the European Union, "COM" for Commission...). More types available at <http://publications.europa.eu/resource/authority/corporate-body>. Optional.
        output_format: Optional output format. Use None or "objects" to return a list of `EurlexOfficialAct` objects, "json" to return a JSON-compatible list of dictionaries, "csv" to return CSV text, "xml" to return XML text, or "df" to return a pandas DataFrame.
    Returns:
        Acts in the requested output format.

    """
    normalized_output_format = _normalize_acts_output_format(output_format)
    query = self._connector.build_acts_query(
        date,
        language=language,
        date_end=date_end,
        title_contains=title_contains,
        category_type=category_type,
        institution_type=institution_type,
    )
    response = self._connector.execute_query(query)
    acts = parse_acts_results(response)
    return _format_acts(acts, normalized_output_format)

get_category_types(language=DEFAULT_LANGUAGE, search=None)

Fetch the list of possible category types from the authority list. This method may last a few minutes due to the size of the authority list.

Parameters:

Name Type Description Default
language str

Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...

 DEFAULT_LANGUAGE
search Optional[str]

Optional case-insensitive substring filter on category type labels.

 None

Returns:

Type Description
list[CategoryType]

A list of CategoryType objects with 'code' and 'label' attributes.
Source code in src/bulletin/eurlex/api/client.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
def get_category_types(
    self, language: str = DEFAULT_LANGUAGE, search: Optional[str] = None
) -> list[CategoryType]:
    """Fetch the list of possible category types from the authority list. This method may last a few minutes due to the size of the authority list.

    Args:
        language: Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...
        search: Optional case-insensitive substring filter on category type labels.

    Returns:
        A list of CategoryType objects with 'code' and 'label' attributes.
    """
    query = self._connector.build_category_types_query(language=language, search=search)
    response = self._connector.execute_query(query)
    return parse_category_types_results(response)

get_institution_types(language=DEFAULT_LANGUAGE, search=None)

Fetch the list of possible institution types from the authority list. This method may last a few minutes due to the size of the authority list.

Parameters:

Name Type Description Default
language str

Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...

 DEFAULT_LANGUAGE
search Optional[str]

Optional case-insensitive substring filter on the label.

 None

Returns:

Type Description
list[InstitutionType]

A list of InstitutionType objects with 'code' and 'label' attributes.
Source code in src/bulletin/eurlex/api/client.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
def get_institution_types(
    self, language: str = DEFAULT_LANGUAGE, search: Optional[str] = None
) -> list[InstitutionType]:
    """Fetch the list of possible institution types from the authority list. This method may last a few minutes due to the size of the authority list.

    Args:
        language: Language code (default: "ENG"). Examples: "ENG", "SPA", "FRA"...
        search: Optional case-insensitive substring filter on the label.

    Returns:
        A list of InstitutionType objects with 'code' and 'label' attributes.
    """
    query = self._connector.build_institution_types_query(language=language, search=search)
    response = self._connector.execute_query(query)
    return parse_institution_types_results(response)

Models

bulletin.eurlex.api.models.EurlexOfficialAct dataclass

Source code in src/bulletin/eurlex/api/models.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
@dataclass
class EurlexOfficialAct:
    act_uri: str
    celex_uri: str
    act_number: str | None
    title: str
    date: date
    section_code: str | None
    subsection_code: str | None
    category_code: str | None
    category_uri: str | None
    category_label: str | None
    institution_code: str | None
    institution_uri: str | None
    institution_label: str | None

    def _to_dict(self) -> dict[str, str | None]:
        """Return a serializable dict representation of the act."""
        return {
            "act_uri": self.act_uri,
            "celex_uri": self.celex_uri,
            "act_number": self.act_number,
            "title": self.title,
            "date": self.date.isoformat(),
            "section_code": self.section_code,
            "subsection_code": self.subsection_code,
            "category_code": self.category_code,
            "category_uri": self.category_uri,
            "category_label": self.category_label,
            "institution_code": self.institution_code,
            "institution_uri": self.institution_uri,
            "institution_label": self.institution_label,
        }

    @classmethod
    def _from_binding(cls, binding: Mapping[str, Any]) -> EurlexOfficialAct:
        """Build an EurlexOfficialAct from one SPARQL binding item."""
        return cls(
            act_uri=_required_value(binding, "act"),
            celex_uri=_optional_value(binding, "celexAct") or _optional_value(binding, "celex") or "",
            act_number=_optional_value(binding, "actNumber"),
            title=_required_value(binding, "title"),
            date=date.fromisoformat(_required_value(binding, "date").split("T")[0]),
            section_code=_optional_value(binding, "sectionCode"),
            subsection_code=_optional_value(binding, "subsectionCode"),
            category_code=_optional_value(binding, "categoryCode"),
            category_uri=_optional_value(binding, "categoryUri"),
            category_label=_optional_value(binding, "categoryLabel"),
            institution_code=_optional_value(binding, "institutionCode"),
            institution_uri=_optional_value(binding, "institutionUri"),
            institution_label=_optional_value(binding, "institutionLabel"),
        )

bulletin.eurlex.api.models.CategoryType dataclass

Represents a category type (resource type) from the authority list.

Source code in src/bulletin/eurlex/api/models.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
@dataclass
class CategoryType:
    """Represents a category type (resource type) from the authority list."""
    code: str
    label: str

    def _to_dict(self) -> dict[str, str]:
        """Return a serializable dict representation of the category type."""
        return {
            "code": self.code,
            "label": self.label,
        }

    @classmethod
    def _from_binding(cls, binding: Mapping[str, Any]) -> CategoryType:
        """Build a CategoryType from one SPARQL binding item."""
        return cls(
            code=_required_value(binding, "code"),
            label=_required_value(binding, "label"),
        )

bulletin.eurlex.api.models.InstitutionType dataclass

Represents an institution type from the authority list.

Source code in src/bulletin/eurlex/api/models.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
@dataclass
class InstitutionType:
    """Represents an institution type from the authority list."""
    code: str
    label: str

    def _to_dict(self) -> dict[str, str]:
        """Return a serializable dict representation of the institution type."""
        return {
            "code": self.code,
            "label": self.label,
        }

    @classmethod
    def _from_binding(cls, binding: Mapping[str, Any]) -> InstitutionType:
        """Build an InstitutionType from one SPARQL binding item."""
        return cls(
            code=_required_value(binding, "code"),
            label=_required_value(binding, "label"),
        )

Constants

bulletin.eurlex.constants.LANGUAGE_CODE_MAP = {'SPA': 'es', 'ENG': 'en', 'FRA': 'fr', 'DEU': 'de', 'ITA': 'it', 'POR': 'pt', 'NLD': 'nl', 'POL': 'pl', 'RON': 'ro', 'BUL': 'bg', 'CES': 'cs', 'DAN': 'da', 'ELL': 'el', 'EST': 'et', 'FIN': 'fi', 'GLE': 'ga', 'HRV': 'hr', 'HUN': 'hu', 'LIT': 'lt', 'LAV': 'lv', 'MLT': 'mt', 'SLK': 'sk', 'SLV': 'sl', 'SWE': 'sv'} module-attribute