HATVP APIhatvp.fr ↗
Access HATVP declarations of interests, assets, and the French lobbyist registry. Search by name, mandate type, department, or browse aggregated statistics.
What is the HATVP API?
This API exposes 8 endpoints covering the French High Authority for Transparency in Public Life (HATVP) dataset, including declarations of interests, patrimony filings, and the lobbyist registry. Use search_declarations to find officials by name, title, or department code, then fetch full structured declaration data — financial participations, real estate holdings, consulting activities, and more — via get_declaration_detail or the patrimony-specific get_patrimony_declaration endpoint.
curl -X GET 'https://api.parse.bot/scraper/3c4be371-aa76-4641-af45-4e5d0719ded1/search_declarations?name=LAHMAR&limit=5&query=Macron&title=D%C3%A9put%C3%A9&offset=0&department=75&type_mandat=depute' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace hatvp-fr-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: HATVP SDK — declarations, lobbyists, and statistics."""
from parse_apis.hatvp_public_declarations_lobbyist_registry_api import (
Hatvp, MandateType, DeclarationNotFound
)
hatvp = Hatvp()
# Get aggregated statistics about published declarations
stats = hatvp.statistics.get()
print(stats.total_declarations, stats.by_type_mandat)
# Search declarations by function type (deputies)
for decl in hatvp.declarations.by_function(function_type=MandateType.DEPUTE, limit=3):
print(decl.nom, decl.prenom, decl.qualite, decl.departement)
# Search by geographic zone (Paris)
first_paris = hatvp.declarations.by_zone(zone="75", limit=1).first()
if first_paris:
print(first_paris.nom, first_paris.type_mandat, first_paris.open_data)
# Get full declaration detail with typed-error handling
try:
detail = hatvp.declarations.detail(xml_filename="lahmar-abdelkader-dia31320-depute-69.xml")
print(detail.uuid, detail.dateDepot)
except DeclarationNotFound as exc:
print(f"not found: {exc.xml_filename}")
# Search lobbyists by sector keyword
for org in hatvp.lobbyists.search(query="energy", limit=3):
print(org.denomination, org.ville, org.identifiantNational)
print("exercised: statistics.get / declarations.by_function / declarations.by_zone / declarations.detail / lobbyists.search")
Search for public official declarations by name, title, or department. Returns matching officials from the HATVP open data CSV with their metadata. At least one filter (query, name, title, department, type_mandat) is recommended to narrow results; omitting all filters returns all declarations. Pagination is manual via offset and limit.
| Param | Type | Description |
|---|---|---|
| name | string | Filter by official's name (matches against first and last name). |
| limit | integer | Maximum number of results to return. |
| query | string | General search across name, first name, and title/position. |
| title | string | Filter by official's title or position (e.g. 'Député', 'Sénateur'). |
| offset | integer | Pagination offset (number of results to skip). |
| department | string | Filter by department code (e.g. '75' for Paris, '13' for Bouches-du-Rhône). |
| type_mandat | string | Filter by mandate type. |
{
"type": "object",
"fields": {
"limit": "integer max results returned",
"total": "integer total number of matching declarations",
"offset": "integer pagination offset",
"results": "array of declaration objects"
},
"sample": {
"data": {
"limit": 5,
"total": 2,
"offset": 0,
"results": [
{
"nom": "MACRON",
"prenom": "Emmanuel",
"qualite": "Président de la République",
"civilite": "M.",
"open_data": "",
"date_depot": "2022-03-01",
"departement": "",
"nom_fichier": "macron-emmanuel-dia20721-president.pdf",
"type_mandat": "president",
"type_document": "dia",
"date_publication": "2022-05-16",
"statut_publication": "Livrée"
}
]
},
"status": "success"
}
}About the HATVP API
Declaration Search and Filtering
search_declarations queries the HATVP open data across fields including civilite, prenom, nom, type_mandat, qualite, type_document, departement, and date_publication. It accepts filters for official name, title (e.g. Député, Sénateur), department code, and mandate type (depute, senateur, president, gouvernement, commune, region). All results are paginated via offset and limit. For use-case-specific browsing, search_by_function and search_by_geographic_zone offer the same paginated result shape filtered to a single function type or French department code (e.g. 75 for Paris, 971 for Guadeloupe).
Declaration Detail Endpoints
Once you have an xml_filename from a search result's open_data field, get_declaration_detail returns the full structured declaration: mandatElectifDto (elected mandates), activConsultantDto (consulting roles), activProfCinqDerniereDto (professional activities over the last five years), participationDirigeantDto (management participations), and participationFinanciereDto (financial participations). DSP (patrimony) declarations are better handled by get_patrimony_declaration, which returns asset-specific sections: immeubleDto (real estate), comptesBancaireDto (bank accounts), valeursMobilieresDto (securities), vehiculeDto, assuranceVieDto, and passifDto (liabilities). The interests-only view is available via get_interests_declaration.
Lobbyist Registry
list_lobbyists queries the HATVP register of interest representatives. Each result object includes denomination, identifiantNational, categorieOrganisation, adresse, codePostal, plus details on directors, collaborators, clients, affiliations, and activity sectors. The endpoint accepts a free-text query parameter that matches across organization name, sector, directors, and collaborators, with offset/limit pagination.
Statistics
get_statistics returns aggregate counts with no required inputs. The response breaks down total declarations by by_type_mandat (mandate type), by_departement (department code), and by_statut_publication (publication status). Useful for understanding dataset coverage before issuing targeted searches.
The HATVP API is a managed, monitored endpoint for hatvp.fr — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when hatvp.fr changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official hatvp.fr API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Map all elected officials in a given French department by combining
search_by_geographic_zonewith department codes. - Build a conflict-of-interest tracker by pulling
activConsultantDtoandparticipationFinanciereDtofields fromget_declaration_detail. - Analyze real estate and securities portfolios of public officials using
immeubleDtoandvaleursMobilieresDtofromget_patrimony_declaration. - Enumerate registered lobbyists in a specific sector using the
queryparameter inlist_lobbyists. - Generate per-mandate-type breakdowns of published declarations with
get_statisticsto inform journalism or research dashboards. - Cross-reference an official's professional history over five years via
activProfCinqDerniereDtoin the interests declaration endpoint. - Filter all government ministers' declarations using
type_mandat=gouvernementinsearch_declarationsfor cabinet-level transparency monitoring.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does HATVP provide an official developer API?+
Which declaration types have detailed XML data available, and which don't?+
get_declaration_detail, get_patrimony_declaration, and get_interests_declaration all require an xml_filename from the open_data field of a search result. Not every declaration record includes this field — only those for which HATVP has published a structured XML file have it populated. Officials without an XML open data entry can be found via search but their detailed field-level content is not accessible through these endpoints.Can I retrieve historical or archived declarations from earlier mandate periods?+
What does `get_statistics` return, and does it support filtering by year?+
get_statistics takes no input parameters and returns three aggregate breakdowns: total declaration count, counts by mandate type (by_type_mandat), counts by department (by_departement), and counts by publication status (by_statut_publication). Year-based filtering is not currently supported. You can fork the API on Parse and revise it to add time-range filtering if your use case requires trend analysis over time.Does the lobbyist endpoint include financial spending figures reported to HATVP?+
list_lobbyists endpoint returns organizational metadata — name, national identifier, category, address, directors, collaborators, clients, and activity sectors. Declared lobbying expenditure amounts are not currently included in the response fields. You can fork the API on Parse and revise it to add spending data if HATVP's registry exposes those figures in a parseable form.