DWZListeREST Resource

GET /dwz/dwzliste/clubs

Retrieves a paginated list of chess clubs.

This endpoint supports filtering via multiple optional query parameters. String-based filters perform a prefix match (LIKE 'value%'). If no parameters are provided, all available clubs are returned.

Query Parameters

• vkz – Filter by club number (VKZ). Supports partial prefix matching. Max length: 255 characters.
• clubName – Filter by club name. Supports partial prefix matching. Max length: 255 characters.
• federationName – Filter by federation name (Verband). Supports partial prefix matching. Max length: 255 characters.
• regionName – Filter by region name (übergeordneter Verband). Supports partial prefix matching. Max length: 255 characters.
• limit – Maximum number of results to return. If omitted, all matching results are returned.
• offset – Zero-based index of the first result to return. Defaults to 0 if omitted.
• includeArchived – If true, deleted clubs are included as well. Defaults to false, i.e. only non-deleted clubs are returned. Applies to this JSON endpoint only; the CSV export always returns non-deleted clubs exclusively.

Field Constraints

• All string-based fields are stored as VARCHAR(255)
• Maximum allowed length for string inputs: 255 characters

Response

• 200 OK – Returns a PagedResponse containing DSBClubDTO objects matching the filters, along with pagination metadata (limit, offset, totalCount) and PageNavigationLinks (self, first, last, next, previous). Each DSBClubDTO contains:
  • clubVkz – Club number (VKZ / Vereinskennziffer)
  • clubName – Name of the club
  • federation – VKZ of the federation (Verband) the club belongs to
  • parentFederation – VKZ of the parent federation (übergeordneter Verband)
  • state – State of the club (DELETE_STATE_FALSE or DELETE_STATE_TRUE)
• 401 Unauthorized – If the subject is not authorized.
• 500 Internal Server Error – If an error occurs while processing the request.

Example

GET /dwz/dwzliste/clubs
Accept: application/json

              

HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "metadata" : {
    "limit" : 12345,
    "offset" : 12345,
    "totalCount" : 12345
  },
  "links" : {
    "self" : "...",
    "first" : "...",
    "last" : "...",
    "next" : "...",
    "previous" : "..."
  },
  "data" : [ {
    "clubVkz" : "...",
    "clubName" : "...",
    "federation" : "...",
    "parentFederation" : "...",
    "state" : "DELETE_STATE_FALSE"
  }, {
    "clubVkz" : "...",
    "clubName" : "...",
    "federation" : "...",
    "parentFederation" : "...",
    "state" : "DELETE_STATE_TRUE"
  } ]
}
                
              

GET /dwz/dwzliste/federations

Retrieves a paginated list of federations.

This endpoint supports filtering via optional query parameters. If no parameters are provided, all available federations are returned.

Query Parameters

• federationName – Filter by federation name (prefix match, max length: 255 characters).
• limit – Maximum number of results to return. If omitted, all matching results are returned.
• offset – Zero-based index of the first result to return. Defaults to 0 if omitted.

Response

• 200 OK – Returns a PagedResponse containing DSBFederationDTO objects matching the filters, along with pagination metadata (limit, offset, totalCount) and PageNavigationLinks (self, first, last, next, previous). Each DSBFederationDTO contains:
  • federationNumber – VKZ of the federation
  • federation – Top-level federation identifier
  • parentFederation – VKZ of the immediate parent federation. null if no parent exists.
  • federationName – Name of the federation
• 401 Unauthorized – If the subject is not authorized.
• 500 Internal Server Error – If an error occurs while processing the request.

Example

GET /dwz/dwzliste/federations
Accept: application/json

              

HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "data" : [ {
    "federationNumber" : "...",
    "federation" : "...",
    "parentFederation" : "...",
    "federationName" : "..."
  }, {
    "federationNumber" : "...",
    "federation" : "...",
    "parentFederation" : "...",
    "federationName" : "..."
  } ],
  "metadata" : {
    "limit" : 12345,
    "offset" : 12345,
    "totalCount" : 12345
  },
  "links" : {
    "self" : "...",
    "first" : "...",
    "last" : "...",
    "next" : "...",
    "previous" : "..."
  }
}
                
              

GET /dwz/dwzliste/persons

Retrieves a list of persons along with their latest known DWZ rating and index and all current club memberships.

This endpoint supports filtering via multiple optional query parameters. If no parameters are provided, all available persons are returned.

A person is included if at least one of their current memberships (a membership without an until date) matches the membership-related filters (clubName, vkz, memberNo, regionName, federationName). Pagination (limit / offset) and totalCount operate on distinct persons, so every person appears once regardless of how many current memberships they have.

Query Parameters

• firstname – Filter by first name (max length: 255 characters)
• lastname – Filter by last name (max length: 255 characters)
• clubName – Filter by club name (max length: 255 characters)
• vkz – Filter by VKZ (prefix match, max length: 255 characters)
• memberNo – Filter by member number
• regionName – Filter by region name (max length: 255 characters)
• federationName – Filter by federation name (max length: 255 characters)
• minRating – Minimum DWZ rating (inclusive)
• maxRating – Maximum DWZ rating (inclusive)
• fideId – Filter by FIDE ID
• gender – Filter by gender (MALE or FEMALE); matches the value exposed in the gender field of each DSBPersonDTO.
• minAge – Minimum age (inclusive). Age is computed as the year of the current checkpoint's reference date minus the person's year of birth, so it only reflects the year of birth (consistent with the data exposed by this API). Persons without a known year of birth are excluded when an age filter is set.
• maxAge – Maximum age (inclusive). Same age definition as minAge.
• limit – Maximum number of results to return. If omitted, all matching results are returned.
• offset – Zero-based index of the first result to return. Defaults to 0 if omitted.

Response

• 200 OK – Returns a PagedResponse containing DSBPersonDTO objects matching the filters, along with pagination metadata (limit, offset, totalCount) and PageNavigationLinks (self, first, last, next, previous). Each DSBPersonDTO includes weekOfLastTournamentEvaluation formatted as YYYYWW (e.g. 202503), indicating the ISO week of the most recent rated tournament the person participated in. null if no rated tournament exists. Each DSBPersonDTO also includes a memberships array holding all current club memberships of the person. Each entry contains:
  • vkz – VKZ (Vereinskennzeichen) of the club
  • memberNo – DSB member number (licence number) within the club
  • clubName – Name of the club
  • licenceState – Licence state of the membership (ACTIVE or PASSIVE).
  • regionName – Name of the region the club belongs to
  • federationName – Name of the federation the club belongs to
  The array contains all current memberships of the person; the membership-related filters only restrict which persons are returned, not which memberships are listed.
• 400 Bad Request – If minAge is greater than maxAge.
• 401 Unauthorized – If the subject is not authorized.
• 500 Internal Server Error – If an error occurs while processing the request.

Example

GET /dwz/dwzliste/persons
Accept: application/json

              

HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "data" : [ {
    "uuid" : "...",
    "nuLigaPersonId" : "...",
    "firstname" : "...",
    "lastname" : "...",
    "birthyear" : 12345,
    "gender" : "MALE",
    "fideId" : 12345,
    "rating" : 12345,
    "index" : 12345,
    "memberships" : [ {
      "vkz" : "...",
      "memberNo" : "...",
      "clubName" : "...",
      "licenceState" : "PASSIVE",
      "regionName" : "...",
      "federationName" : "..."
    }, {
      "vkz" : "...",
      "memberNo" : "...",
      "clubName" : "...",
      "licenceState" : "ACTIVE",
      "regionName" : "...",
      "federationName" : "..."
    } ],
    "weekOfLastTournamentEvaluation" : "..."
  }, {
    "uuid" : "...",
    "nuLigaPersonId" : "...",
    "firstname" : "...",
    "lastname" : "...",
    "birthyear" : 12345,
    "gender" : "FEMALE",
    "fideId" : 12345,
    "rating" : 12345,
    "index" : 12345,
    "memberships" : [ {
      "vkz" : "...",
      "memberNo" : "...",
      "clubName" : "...",
      "licenceState" : "ACTIVE",
      "regionName" : "...",
      "federationName" : "..."
    }, {
      "vkz" : "...",
      "memberNo" : "...",
      "clubName" : "...",
      "licenceState" : "ACTIVE",
      "regionName" : "...",
      "federationName" : "..."
    } ],
    "weekOfLastTournamentEvaluation" : "..."
  } ],
  "metadata" : {
    "limit" : 12345,
    "offset" : 12345,
    "totalCount" : 12345
  },
  "links" : {
    "self" : "...",
    "first" : "...",
    "last" : "...",
    "next" : "...",
    "previous" : "..."
  }
}
                
              

GET /dwz/dwzliste/download/{fileName}

Downloads the DWZ list for a specific federation as a ZIP archive in the official DSB format.

All three CSV files are filtered to only include records belonging to the specified federation (persons and clubs by VKZ prefix, federations by their top-level VKZ character). The special value 0 disables all filtering and returns the complete unfiltered dataset. The archive is generated at most once every 15 minutes per unique combination of federation, charset and delimiter, and cached in memory thereafter.

Path Parameters

• fileName – Name of the returned ZIP file (e.g. LV-B-dwzliste.zip). The character at index 3 is extracted as the federation identifier (case-insensitive, converted to uppercase internally) and must be one of: 0–9, A–H, L, M. The filename must be at least 4 characters long.

Query Parameters

• charset – Character encoding of the CSV files. Defaults to windows-1252 (ANSI, DSB-compatible). Any IANA charset name supported by the JVM is accepted (e.g. utf-8).
• delimiter – Field delimiter used in the CSV files. Defaults to ,. Only the first character of the value is used.

Archive Contents

• spieler.csv – Persons whose club VKZ starts with the federation identifier, sorted by DWZ. One row per current club membership, so a person with several current memberships (memberships without an until date) produces one row per club. Columns: {@code ID, ZPS, Mitgliedsnummer, Status, "Name,Vorname", Geschlecht, Spielberechtigung, Geburtsjahr, WocheLetztesRatingturnier, DWZ, Index, FIDE-Elozahl, FIDE-Titel, FIDE-ID, FIDE-Land, Vorname, Nachname}. ZPS, Mitgliedsnummer and Status reflect the respective membership. Spielberechtigung, FIDE-Elozahl, FIDE-Titel and FIDE-Land are always empty. Status is A (aktiv) or P (passiv). Geschlecht is M (männlich) or W (weiblich).
• vereine.csv – Clubs whose VKZ starts with the federation identifier, sorted by ZPS-Nummer. Columns: ZPS-Nummer, Landesverband, UebergeordneterVerband, Vereinsname.
• verbaende.csv – Federations belonging to the specified federation group, sorted by Verbandnummer. Columns: Verbandnummer, Landesverband, UebergeordneterVerband, Verbandname.
• README.txt – Header with the top-level federation name, generation date, record counts, charset and delimiter, plus column documentation for all three CSV files.

Response

• 200 OK – Returns the ZIP archive as application/zip with Content-Disposition: attachment; filename="".
• 401 Unauthorized – If the subject is not authorized.
• 404 Not Found – If fileName is shorter than 4 characters, the character at index 3 is not a valid federation identifier (0–9, A–H, L, M), or charset is not supported by the JVM.
• 500 Internal Server Error – If an error occurs while building the archive.

Example

GET /dwz/dwzliste/download/{fileName}
Accept: application/zip

              

HTTP/1.1 200 OK
Content-Type: application/zip

                
...
                
              

GET /dwz/dwzliste/persons/{nuLigaId}

Retrieves a single person with their latest known DWZ rating and index and all current club memberships.

Response

• 200 OK – Returns a DSBPersonDTO matching the given nuLigaId. The DTO includes a memberships array holding all current club memberships (memberships without an until date), each with vkz, memberNo, clubName, licenceState, regionName and federationName. See DSBPersonDTO.
• 401 Unauthorized – If the subject is not authorized.
• 404 Not Found – If no person with the given nuLigaId exists.
• 500 Internal Server Error – If an error occurs while processing the request.

Example

GET /dwz/dwzliste/persons/{nuLigaId}
Accept: application/json

              

HTTP/1.1 200 OK
Content-Type: application/json

                
{
  "uuid" : "...",
  "nuLigaPersonId" : "...",
  "firstname" : "...",
  "lastname" : "...",
  "birthyear" : 12345,
  "gender" : "MALE",
  "fideId" : 12345,
  "rating" : 12345,
  "index" : 12345,
  "memberships" : [ {
    "vkz" : "...",
    "memberNo" : "...",
    "clubName" : "...",
    "licenceState" : "PASSIVE",
    "regionName" : "...",
    "federationName" : "..."
  }, {
    "vkz" : "...",
    "memberNo" : "...",
    "clubName" : "...",
    "licenceState" : "ACTIVE",
    "regionName" : "...",
    "federationName" : "..."
  } ],
  "weekOfLastTournamentEvaluation" : "..."
}