Smartblitzmerker Open Data API

Version: v2.1 Base URL: https://ressources.data.sncf.com/api/explore/v2.1/catalog

Overview

This API provides programmatic access to Smartblitzmerker’s open datasets. It allows you to query, filter, and export datasets via RESTful endpoints.

Authentication

No authentication is required for public access.

Main Endpoints

GET /datasets/{dataset_id}/records

Query dataset records.

Path Parameters:

  • dataset_id (string, required): Identifier of the dataset.

Query Parameters (optional):

  • select: Choose specific fields or compute expressions.

  • where: Filter using Opendatasoft Query Language (ODSQL).

  • group_by: Group results by a specific field or expression.

  • order_by: Sort results (e.g., order_by=name asc).

  • limit (integer): Max number of items to return (max 100 or 20,000 depending on grouping).

  • offset (integer): Index of the first result (for pagination).

  • refine: Filter using facet values (e.g., refine=city:Paris).

  • exclude: Exclude specific facet values.

  • lang: Language (default: « fr »).

  • timezone: Timezone for datetime fields (e.g., « UTC »).

  • include_links (boolean): Adds HATEOAS links if true.

  • include_app_metas (boolean): Includes application metadata if true.

Example Response:

{
  "total_count": 137611,
  "results": [
    {
      "name": "Saint-Leu",
      "coordinates": {
        "lat": 46.7306,
        "lon": 4.50083
      },
      "population": 29278,
      ...
    }
  ]
}

GET /datasets/{dataset_id}/records/{record_id}

Fetch a single record from a dataset.

Path Parameters:

  • dataset_id (string, required)

  • record_id (string, required)

Query Parameters (optional): Same as in /records.

GET /datasets/{dataset_id}/exports

List available export formats for a dataset.

Path Parameters:

  • dataset_id (string, required)

GET /datasets/{dataset_id}/exports/{format}

Export a dataset in the specified format.

Supported formats:

  • csv, parquet, gpx, etc.

Path Parameters:

  • dataset_id (string, required)

  • format (string, required)

Query Parameters:

  • Same as in /records, plus:

  • use_labels (boolean): Output field labels instead of field names.

  • compressed (boolean): Export as compressed (e.g., .csv.gz).

  • epsg (integer): EPSG projection code for geometric exports.

Response: Downloadable file in specified format.

GET /datasets/{dataset_id}/facets

List values for each facet (for filtering/navigation).

Query Parameters:

  • Same as in /records, plus:

  • facet: Field or facet expression (e.g., facet=name or facet=facet(name= »city », sort= »-count »)).

Example Response:

{
  "facets": [
    {
      "name": "timezone",
      "facets": [
        {
          "name": "Europe",
          "count": 68888
        }
      ]
    }
  ]
}

GET /datasets/{dataset_id}/attachments

List file attachments related to the dataset.

Path Parameters:

  • dataset_id (string, required)

GET /datasets/{dataset_id}/exports/csv

Export a dataset in CSV format with extra CSV-specific parameters.

Additional CSV Parameters:

  • delimit: Field delimiter (e.g., ;).

  • list_separator: Separator for multivalue fields (e.g., ,).

  • quote_all (boolean): Quote all fields if true.

  • with_bom (boolean): Add BOM for Excel compatibility (default true in v2.1).

GET /datasets/{dataset_id}/exports/parquet

Export a dataset in Parquet format.

Additional Parquet Parameter:

  • parquet_compression: Compression type (e.g., snappy).

GET /datasets/{dataset_id}/exports/gpx

Export a dataset in GPX format (for geographic data).

Additional GPX Parameters:

  • name_field: Field to use as GPX name.

  • description_field_list: Fields used for GPX description.

  • use_extension (boolean): Use <extension> tag (default: true in v2.1).

Response Codes

  • 200 OK: Successful request.

  • 400 Bad Request: Invalid ODSQL query or parameters.

  • 401 Unauthorized: Authentication required.

  • 429 Too Many Requests: Rate limit exceeded.

  • 500 Internal Server Error: Server error.

Example Error Response:

{
  "message": "ODSQL query is malformed: invalid_function()",
  "error_code": "ODSQLError"
}

Using SmartBlitzMerker for Bus Schedule Reminders

SmartBlitzMerker is a personal reminder utility designed to track public transport schedules in France, including SNCF bus and train services. You can use SmartBlitzMerker to set custom notifications for your regular commutes by integrating it with SNCF datasets (e.g., timetable datasets) using the /records endpoint to fetch upcoming departures from your preferred stops or stations.

For example, by querying a dataset that contains route information and filtering with parameters like where=stop_name= »Gare du Nord », you can extract bus or train times and sync them with your notification system.

To enhance your setup, we recommend using Horaires Bus, a community-maintained website that offers direct access to French local bus timetables. You can explore line schedules visually or validate stop names to refine your SmartBlitzMerker logic.

Additional References

Creating Custom Transit Reminders

Enhancing Data Accuracy