A marathon tracking screen can look precise while showing much less than a spectator assumes. A recorded checkpoint passage is an observation at a place and time. It is not continuous knowledge of where the runner is now. A results application becomes more trustworthy when it preserves that distinction throughout its model and interface.
This guide proposes a timing-data design for marathon applications, not a live RacingAPI.com tracking service. Our marathon racing API page explains the main fields, and the sample explorer uses fictional participants. The goal is to help developers present the information they actually have without inventing certainty between observations.
Identify the race and its timing configuration
Start with the event, the particular race distance, and the timing configuration. A meeting can contain multiple races, waves, or categories. Keep those relationships explicit instead of assuming that every participant shares one starting reference.
A timing provider's configuration determines how its published fields should be interpreted. The RACE RESULT support resources provide a gateway to its product documentation and timing guidance. Consult the applicable provider documentation and the organizer's configuration before interpreting a production feed.
For your own model, record which source supplied the observations and which version of your adapter transformed them. A bib number alone is not a permanent participant identity across events. Scope display numbers to the event and preserve a stable source entry identifier.
Distinguish gun time from net time
A gun-time model measures from a defined common starting reference to the finish. A net-time or chip-time model can measure from an individual's recorded start passage to the finish. Which timing value governs an actual award or classification depends on the event's applicable rules and published decisions.
Do not choose the ranking basis silently. Label the displayed time and retain separate fields for each value when provided. If you calculate an illustrative net duration from two timestamps, mark it as an application calculation rather than a published official result.
Keep wave identity and start reference available. A screen that compares durations from different timing bases without explanation may give the wrong impression even when every numeric subtraction is correct. Clear labels are part of correctness, not merely interface polish.
Represent checkpoints as a course structure
Create a checkpoint definition that includes an identifier, a display label, and a course position or distance where appropriate. Keep observations as separate records referencing that definition and the participant entry.
A checkpoint label should not be your only key. Similar labels can occur on multiple loops, and a course can change between event editions. Include the course version or race context needed to distinguish those cases.
Do not assume every participant has a valid observation at every checkpoint. A missing read is missing information. Your interface may display a pending or unavailable split, but it should not automatically infer withdrawal, disqualification, or an impossible pace from that absence.
Separate raw reads from accepted splits
A timing system can produce observations that require interpretation before they become published splits. Your application should consume the provider's documented published results where that is the intended integration, rather than assuming every raw observation is already a valid checkpoint passage.
If your project is explicitly responsible for processing raw reads, keep the original observations and the acceptance rule separate. Record duplicate handling, minimum intervals, checkpoint ordering, and any manual correction workflow as part of that processing design.
Do not present those suggested checks as a replacement for qualified event timing operations. A public results widget and the system that determines official race outcomes have different responsibilities. Define which role your software actually performs.
Calculate pace from clearly defined intervals
For an illustrative interval pace, use the difference between two accepted elapsed times divided by the distance between the corresponding checkpoints. Verify that both intervals use the same timing basis and that the distance difference is positive.
For example, fictional accepted durations of twenty-five and fifty minutes at five and ten kilometres imply a five-minute-per-kilometre interval over that segment. This is arithmetic on the stated inputs, not proof of the runner's current speed or the accuracy of the underlying course measurement.
Avoid calculating a segment from one accepted split and one raw or estimated observation without saying so. Keep cumulative pace separate from interval pace, and name both in the interface. They answer related but different questions.
Label estimates as estimates
A projected finish time can be a useful optional feature, but it is a model output, not a measured result. Identify the input checkpoint, the assumption used for remaining pace, and the time the estimate was calculated.
Do not display an estimated location as if it came from a positioning sensor. If your model places a runner between checkpoints, use a distinct symbol and an explanation. A stale checkpoint can make the estimate increasingly uncertain even if the animation remains smooth.
For a first release, it may be better to show the last recorded checkpoint and its timestamp without a moving map. This modest view tells the spectator something useful while avoiding a claim the available data cannot support.
Preserve privacy in participant displays
Publish only the participant information authorized for the event's public results. Avoid adding contact details, precise birth dates, or other unnecessary personal data to a demonstration or public widget. The existence of a private registration field does not make it a suitable display field.
Use invented names and identifiers in fixtures. That lets you test formatting and correction cases without exposing real athletes. In production, define how corrected names and removal requests reach the appropriate organizer or data controller.
Consider whether categories or participant groups require special presentation decisions. Do not infer sensitive characteristics from names or timing records. Keep the public schema narrow and document the purpose of each field.
Handle finishing state separately from duration
An entry can have recorded intermediate splits without a published finish. A missing finish duration should not automatically become a did-not-finish label. Let the source or authorized race process provide the participation and classification state.
Likewise, a published time and a classification decision can be distinct. Retain both when supplied, and show whether the result remains provisional. Do not erase a correction because the finish timestamp itself did not change.
When a revised result arrives, update the correct event entry and keep an observation or revision marker. Stable identifiers help prevent duplicate rows when a bib number or display name is corrected after the event.
Test a realistic sequence of timing updates
Create a fictional participant with a start, two accepted splits, and a finish. Then create variants with a missing middle split, a duplicate observation, an out-of-order delivery, and a revised finish record. Write the expected public display for each.
Add two waves with different starting references and confirm that the interface does not mix their timing bases. Test an event spanning midnight and verify that timezone-aware timestamps still produce the intended durations.
Finally, test source failure after an initially successful load. Retain the last known snapshot with a visible stale state where that fits your product. A blank screen and a silently outdated result are both less useful than a clear account of what remains known.
Conclusion: show observations before predictions
A dependable marathon application distinguishes timing bases, checkpoint definitions, accepted splits, estimates, and classification state. It keeps participant information minimal and makes missing observations understandable.
Build a small running results example before adding projections or maps. When users can tell the difference between a recorded passage and an estimate, your interface is better prepared for an authorized production timing integration.
