hatvp.fr APIhatvp.fr ↗
Access HATVP declarations of interests, assets, and the French lobbyist registry. Search by name, mandate type, department, or browse aggregated statistics.
curl -X GET 'https://api.parse.bot/scraper/3c4be371-aa76-4641-af45-4e5d0719ded1/search_declarations?limit=3&query=Macron' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for public official declarations by name, title, or department. Returns matching officials from the HATVP open data CSV with their metadata. Supports pagination 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 (e.g. 'depute', 'senateur', 'president', 'gouvernement', 'commune', 'region', 'departement', 'epci', 'europe', 'ctsp', 'autre'). |
{
"type": "object",
"fields": {
"limit": "integer max results returned",
"total": "integer total number of matching declarations",
"offset": "integer pagination offset",
"results": "array of declaration objects with fields: civilite, prenom, nom, type_mandat, qualite, type_document, departement, date_publication, date_depot, nom_fichier, open_data, statut_publication"
},
"sample": {
"data": {
"limit": 3,
"total": 2,
"offset": 0,
"results": [
{
"nom": "MACRON",
"prenom": "Emmanuel",
"qualite": "Président de la République",
"civilite": "M.",
"open_data": "",
"url_photo": "",
"classement": "macronaaaemmanuel5835",
"date_depot": "2022-03-01",
"id_origine": "",
"departement": "",
"nom_fichier": "macron-emmanuel-dia20721-president.pdf",
"type_mandat": "president",
"url_dossier": "/pages_nominatives/macron-emmanuel",
"type_document": "dia",
"date_publication": "2022-05-16",
"statut_publication": "Livrée"
}
]
},
"status": "success"
}
}About the hatvp.fr 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.
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.
- 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 | 250 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.