Additional Guidelines
General
Analyticom REST API is a subset of endpoints that can be used to retrieve COMET data and make it available to 3rd party systems. To make it as simple as possible we have separated the data into several key endpoints (competition, matches, match players...), making it easy to integrate by a variety of 3P systems, websites, etc., all over the world.
Usage
Please take into account that the MOST important point is the following:
The REST API should be used to synchronize data from COMET with a local/web database.
💡 Each time someone is looking at your website and clicking around, you should NOT be sending API requests for COMET data.
💡 Most COMET data does not change with such high frequency, so there is no reason to keep asking for the same data repeatedly.
👉 For example, there is no need to request a list of active competitions EACH TIME EACH VISITOR clicks on some page. With this type of configuration and a large amount of data, you will cause the REST API to generate timeout errors very quickly due to controlled request rates (i.e. there is a limit to the number of requests per second).
👉 Let's look at more examples - the list of matches in a competition. In COMET, the list of matches is generated at the start of the season and it very rarely changes. So, there is absolutely no need to keep sending API requests to get the same list of matches all the time. At most, you can schedule a refresh request at some low frequency (let's say once a week ... even that is too much) and it should be done independently of any web visits and clicks. The list of matches for a competition, just like all other data obtained via API requests, should be stored in a local database.
Example: https://api-<tenant>.analyticom.de/api/export/comet/competition/12345/matches
👉 Now let's take an example with the details of some specific match. The first endpoint starts with basic information about the match.
/api/export/comet/match/{matchFifaId}
After that, there are additional endpoints for getting match events, match cases, match phases, match officials, match players, etc.
/api/export/comet/match/{matchFifaId}/events
/api/export/comet/match/{matchFifaId}/cases
/api/export/comet/match/{matchFifaId}/phases
/api/export/comet/match/{matchFifaId}/officials
etc...
💡 Match data will change more often than the competition data, however, still not too frequently (during some reasonable amount of time before the match, and then at most a few days after the match). You can use the following endpoints to test which matches have been recently updated:
/api/export/comet/match/{matchFifaId}/latest/events
/api/export/comet/match/{matchFifaId}/lastUpdateDateTime
/api/export/comet/match/{matchFifaId}/latest/events
This endpoint will provide you all events that happened in the last n seconds.
This could be useful for a "live score" feature on your website ... if you plan to have that.
/api/export/comet/match/{matchFifaId}/lastUpdateDateTime
This endpoint will provide you the last time some match was updated if you want to make sure that no changes have been made since your last API request.
To summarize everything, here is what you need to do:
Setup/configure a local database for your website with the appropriate structure.
Change the data source for your webpages, so they read the data from a local database.
Use the API requests ***when necessary*** to synchronize the data from COMET to local db.
Schedule the API calls appropriately.
I hope these examples are helpful to you.
If you need additional assistance, feel free to send us specific questions.