Endpoints

Endpoints are the primary way you interact with the ESPN API through this client. They are fluent, chainable, and mirror the nesting of the ESPN URL hierarchy.

How endpoints work 

Every endpoint is reached from the EspnApiClient instance through a method named after the resource. Calling that method returns an endpoint object; calling a method on that object either fetches data or descends one level deeper into the hierarchy.

// One level: a list of all venues
$venueRefs = $client->venues()->listRefs();

// Two levels: the teams that belong to a season
$teamRefs = $client->seasons()->teams()->listRefs(2025);

// Four levels: a single competitor in a competition of an event
$competitor = $client->events()
    ->competitions()
    ->competitors()
    ->get(401773010, 401773010, 12);

The chain itself performs no requests. Only the terminal get* / list* call triggers an HTTP call. Intermediate calls like ->competitions() are cheap object constructions, so you can build and reuse them freely.

Two kinds of calls 

Every endpoint exposes two families of terminal methods.

`get*()` — fetch one resource 

A get call requests a single resource by its identifiers and returns a fully populated DTO, or null if ESPN has no such resource.

$team = $client->seasons()->teams()->get(2025, 12);

if (null === $team) {
    // ESPN returned an empty body for this resource
}

`listRefs*()` — fetch a list of references 

ESPN list endpoints do not return full objects. They return a paginated envelope whose items array contains $ref links. The client extracts those links and returns them as a plain array of URL strings. You then fetch each referenced resource individually.

$athleteRefs = $client->seasons()->athletes()->listRefsForTeam(2025, 12);

// $athleteRefs is now:
// [
//   'http://sports.core.api.espn.com/v2/.../athletes/2578570?...',
//   'http://sports.core.api.espn.com/v2/.../athletes/3045147?...',
//   ...
// ]

This deliberate split keeps list calls cheap and lets you decide how many referenced resources you actually want to resolve. See References for how to turn a reference string back into a typed DTO.

Working with references 

Because list calls and many DTO properties return reference strings rather than objects, a common pattern is to list references and then resolve each one:

$positionRefs = $client->positions()->listRefs();

foreach ($positionRefs as $ref) {
    // Resolve the numeric id from the reference and fetch the position
    // (see "References" for a helper-free way to do this)
    $position = $client->get(
        $client->getUriFactory()->createUri($ref),
        \HansPeterOrding\EspnApiClient\Dto\EspnPosition::class
    );

    echo $position->getDisplayName();
}

The EspnApiClient::get() method accepts any UriInterface plus the DTO class to deserialize into, which makes resolving a raw reference string straightforward.

Base URIs 

ESPN exposes two hosts. The client uses the sports core API by default, which is the richly linked, resource-oriented API that powers everything in this client:

Constant	Value
`BASE_URI_SPORTS_CORE`	`https://sports.core.api.espn.com/v2/sports/football/leagues/nfl/`
`BASE_URI_SITE`	`https://site.api.espn.com/apis/site/v2/sports/football/nfl/`

Both constants live on EspnApiClientInterface.

Endpoint reference 

The table below lists every endpoint chain and its terminal methods. The chain column shows how to reach the endpoint from the client.

Top-level resources 

Season hierarchy 

Teams, athletes, coaches 

Events, competitions, scoring 

Note

A few endpoints have shape-specific helpers. records() and teams() provide group-scoped variants (getForGroup, getForSeasonGroup) because ESPN exposes the same resource under both a team-scoped and a group-scoped URL. standings() returns raw arrays via getAsArray rather than a DTO, because standings are consumed as a feed of record references rather than a standalone entity.