Query parameters

Why they matter

– Dynamically adjust content: For example, ?sort=price_asc&page=2 could reorder and narrow down product listings.
– Track user activity: Marketers use UTM tags like ?utm_source=facebook&utm_campaign=spring_sale for campaign analytics.
– Enable API flexibility: RESTful endpoints often use parameters for filtering, pagination, and configuration without altering the URL path.

Anatomy of query parameters

Query parameters are an essential part of modern web communication. They appear in URLs as optional key-value pairs, shaping how data is requested or delivered. Here’s how they work, how they’re encoded, and how a typical API uses them in practice.

Structure overview

A URL with query params typically looks like this.

https://api.sportmonks.com/v3/football/teams?api_token=TOKEN&include=squad;stats

Let’s break it down:

– Base URL: Everything before the ?
E.g., https://api.sportmonks.com/v3/football/teams
– Query string separator: The ? symbol, which marks the beginning of query parameters.
– Query string: Everything after the ?
In the example: api_token=TOKEN&include=squad;stats
– Parameters: These are the individual key=value pairs, separated by &.
    – api_token=TOKEN provides authentication.
    – include=squad;stats asks the API to return extra data (squad details and statistics).

While older systems sometimes allowed ; as a separator, the modern standard and W3C’s recommendation is to use & for consistency and compatibility across clients.

Encoding essentials

URLs must use ASCII, which means any special characters must be percent-encoded.

– Unsafe characters like !, @, and & become % followed by two hexadecimal digits.
– Spaces may be represented as %20 or +, with + being more common in form submissions.

Examples

"Hello World & Welcome!" → Hello%20World%20%26%20Welcome%21

Reserved characters (like =, &, ?, /) should only be used for their intended function in the URL. If used in parameter values, they must be encoded.

Reserved vs. unreserved characters

According to RFC 3986, characters in URLs fall into two categories:

– Unreserved characters:
These can appear without encoding:
A-Z, a-z, 0-9, –, _, ., ~

– Reserved characters:
These include symbols like :, /, ?, =, &, ;, # and must be percent-encoded when not used in their default roles.

Encoding APIs in practice

Most programming languages provide built-in functions to encode and decode query parameters:

– JavaScript:
      – encodeURIComponent() – for encoding values
      – encodeURI() – for entire URLs

– Python:
      – urllib.parse.quote() and unquote()

– PHP
      – rawurlencode() and urldecode()

Putting it all together: A live URL example

Let’s build a query programmatically in JavaScript:

const base = "https://api.sportmonks.com/v3/football/players";
const params = new URLSearchParams({
  api_token: "YOUR_TOKEN",
  search: "Erling Haaland",
  include: "team;stats"
});
console.log(base + "?" + params.toString());
// Output:
// https://api.sportmonks.com/v3/football/players?api_token=YOUR_TOKEN&search=Erling+Haaland&include=team%3Bstats

What’s happening here

– Each key and value is automatically encoded.
– The space in “Erling Haaland” becomes +.
– The semicolon ; in the include parameter is encoded as %3B to avoid confusion with traditional delimiters.

Why the syntax matters

– Clarity for servers: Clearly structured query strings make it easier for servers to parse requests reliably.
– Interoperability: Proper encoding ensures compatibility across browsers, libraries, and devices.
– Security: Encoding helps avoid injection attacks, broken requests, or unexpected behaviour.

Common use cases for query parameters

Query parameters offer a flexible way to customise content delivery and request behaviour, without altering the base URL. These fall into two main types: active parameters, which affect what content is shown, and passive ones, used for metadata, tracking, or analytics.

Active parameters

These change what the user or client receives from a request. Sportmonks APIs, like many modern RESTful services, use them for precise content control.

Filtering & sorting

– E-commerce-like scenario
On a product site, you might see ?category=electronics&sort=price_asc to sort results by ascending price.

Pagination

https://api.sportmonks.com/v3/football/teams?api_token=TOKEN&page=3

Sportmonks uses page-based navigation. Large datasets can be accessed chunk by chunk via page and per_page parameters.

Search queries

https://api.sportmonks.com/v3/football/players/search?api_token=TOKEN&search=Mbappe

This fetches players matching the keyword “Mbappe”.

Passive parameters

These don’t alter displayed content but are essential for tracking, analytics, or session handling:

Session & affiliate tracking

– Example: ?sessionid=xyz123, though most sites now prefer cookies.
– Affiliate tags such as ?ref=partner123 helps identify traffic sources.

Marketing campaign tags (UTM)

– Common in digital marketing: ?utm_source=twitter&utm_medium=social&utm_campaign=spring_sale.
– These are parsed by analytics platforms (e.g., Google Analytics) to attribute traffic and conversions.

Technical & SEO implications

Query parameters have a big role in SEO, user experience, and crawl management. Without thoughtful implementation, they can cause serious issues for your site’s search performance.

Duplicate content & crawl budget

– Multiple URL variations with similar or identical content can cause search engines to interpret them as distinct pages, fragmenting ranking signals. This weakens visibility and authority for each URL.
– Wasted crawl budget occurs when bots crawl nearly identical pages repeatedly, slowing down discovery of important unique content.

Canonical tags

– Using <link rel=”canonical” href=”https://example.com/page”> instructs search engines which version is the master copy, consolidating link equity and crawling priority.
– Canonicals enhance crawl efficiency by guiding bots away from duplicates, ensuring they index your most valuable pages.

As a best practice, always use absolute URLs in canonical tags, match internal links to canonical versions and use self-referential canonicals for parameterised pages.

Google search console URL parameter tool

– This tool enables you to configure how Googlebot treats specific parameters: e.g. mark ?ref= or ?utm_ as “No Effect” so they aren’t crawled. Mark content-changing parameters (e.g. ?sort=price) as “Sorts” or “Narrows”.
– Proper setup can drastically reduce redundant page crawling and improve indexing of vital content.

Robots.txt & noindex directives

– Use robots.txt to disallow crawling of parameterised URLs only when parameters don’t influence content (e.g. session IDs, UTM tracking).
– For parameter combinations that generate near-duplicate content but need to remain crawlable (e.g., filtered or paged versions), use <meta name=”robots” content=”noindex, follow”> and pair with canonical tags.

URL cleanliness & UX

– Short, meaningful URLs are easier to share, remember, and trust, improving click-through rates.
– Clean URLs are also more resistant to data-entry and parsing issues.

Sportmonks: A live example of query parameters in action

Sportmonks is a sports data provider whose RESTful APIs for football, cricket, and Formula 1 rely heavily on query parameters to customise responses:

– Authentication: Every request requires an api_token as a query parameter (e.g., ?api_token=YOUR_TOKEN), allowing personalised and secure access .
– Filtering & pagination:
      – Use &page= (and optionally &per_page=) to navigate large result sets, e.g. ?api_token=…&page=2&per_page=50 .
      – The filters= parameter targets specific data, like only fetching goal events.
– Includes: The include= parameter lets clients request related resources in the same call e.g., include=team;stats enriches base endpoints with squad and stats data .
– Sorting: With sortBy= and order=, you can determine how collections are sorted (by date, name, etc.) .

Why Sportmonks matters here

We enable API flexibility, allowing clients to fetch exactly what they need, authenticated access, pagination, filtering, sorting, and relational data inclusion in a single, coherent URL.

Control your data flow with query precision

Query parameters give your apps the power to filter, sort, paginate, and customise API responses without messy code or complex endpoints. Sportmonks’ APIs are built with this flexibility in mind, from player stats and team data to live match events, you choose exactly what you want, when you want it.

Try Sportmonks free for 14 days and see how simple, powerful API calls can transform your sports platform.