charts.hohli.com

OpenAPI-generated API documentation is reference documentation that is produced automatically from an OpenAPI description file rather than written by hand. You write (or generate) a machine-readable specification of your API — endpoints, parameters, request bodies, responses, schemas, and auth — and a documentation tool reads that file and renders a browsable, often interactive reference site. The spec becomes the single source of truth; the docs become a build artifact.

This differs from manually written docs in one fundamental way: with hand-written docs, the prose is the source of truth and the API is described separately. With spec-driven docs, the API description is the source, and every page, table, and code sample is derived from it.

How the workflow actually runs

A typical spec-driven documentation pipeline has five stages:

1. Author or generate the spec. You either write an OpenAPI document by hand (YAML or JSON), or generate it from code annotations, framework metadata, or a design-first editor. Design-first means the spec is written before implementation; code-first means it is extracted from existing code.
2. Validate and lint. The spec is checked against the OpenAPI schema and against style rules — consistent naming, required descriptions, no undocumented 4xx responses, no orphaned schemas.
3. Bundle and transform. Multi-file specs are combined, $ref pointers are resolved, and the document is optionally split into per-tag or per-version outputs.
4. Render. A documentation tool converts the spec into HTML: an endpoint list, a sidebar of operations, parameter tables, response schemas, and a "try it" console.
5. Publish and version. The rendered site is deployed, and each API version gets its own snapshot so consumers can read docs matching the version they call.

Steps 2 through 5 are usually automated in CI. If the spec fails validation, the docs build fails — which is the point.

Spec-driven vs. hand-written documentation

The practical conclusion most teams reach: generate the reference, write the guides. Reference material is repetitive and mechanical, which is exactly what generation is good at. Conceptual explanations, migration notes, and tutorials carry judgment that a spec cannot express.

What you get out of the box

Generated reference pages commonly include:

• An operation list grouped by tag or path, with HTTP method and path.
• Parameter tables showing name, location (path, query, header, cookie), type, required flag, and description.
• Request and response schemas rendered as expandable trees, including nested objects and arrays.
• Authentication details pulled from the securitySchemes section.
• Interactive request consoles that let a reader send a real call from the browser.
• Generated code samples in several languages, derived from the same schemas.
• Multiple output formats, such as a static site, a single HTML file, or a mock server.

Because all of these come from one document, changing a field name in the spec updates the parameter table, the schema tree, and every code sample at once.

Where spec-driven documentation breaks down

Generation is not free. The trade-offs are real:

Spec quality becomes documentation quality. A field with no description produces a table row with an empty cell. A vague summary produces a vague heading. Tools can enforce presence of descriptions via linting, but they cannot enforce that the description is useful.

Customization has limits. If you need a page that does not map to an OpenAPI concept — a conceptual overview, a pricing explanation, a comparison of two endpoints — you write it outside the generator and link to it.

Not everything is expressible. Webhooks, streaming responses, long-polling behavior, and complex multi-step flows are awkward or impossible to describe fully in OpenAPI. Those need prose.

The spec can go stale. If the spec is maintained separately from the implementation, it drifts just like hand-written docs. The mitigation is to generate the spec from code, or to test the implementation against the spec in CI.

Interactive consoles need care. A "try it" button that hits a production API with real credentials is a security and rate-limit problem. Point it at a sandbox, or disable it.

Deciding whether to adopt it

Adopt spec-driven reference documentation if most of these are true:

• Your API has more than a handful of endpoints, or changes frequently.
• You ship client SDKs or code samples in more than one language.
• Multiple teams consume the API and need a consistent, always-current reference.
• You already have, or are willing to maintain, an OpenAPI description.

Stay with hand-written docs, or a hybrid, if:

• Your API is small and stable, and the reference fits on one page.
• Your documentation is mostly conceptual and contains little endpoint-level detail.
• You cannot commit to keeping the spec in sync with the implementation.

A reasonable middle path: generate the reference from the spec, and hand-write the getting-started guide, authentication walkthrough, and error-handling page. Link the two directions so readers can move from concept to endpoint and back.

A minimal starting checklist

1. Produce one valid OpenAPI document for a single API version.
2. Add a linter with rules for descriptions, operation IDs, and error responses.
3. Wire the docs build into CI so a failing spec fails the build.
4. Render the reference and review it as a reader, not as the author.
5. Write the two or three conceptual pages the generator cannot produce.
6. Version the published docs alongside the API version.

The core idea is simple: describe the API once, in a format both machines and humans can read, and let the reference documentation fall out of that description. Everything else — tooling, hosting, interactivity — is a detail on top of that decision.

You can build a chart online by entering a dataset into a browser-based builder, choosing a chart type and style, previewing it at a target canvas size, and then generating the final chart. The Online Charts Builder at charts.hohli.com works this way: it is a service for working with the Google Charts API, which dynamically generates charts from your input data and style settings. This walkthrough covers the full sequence — data entry, customization, preview sizing, generation, and the problems that most often stop a chart from rendering.

What you need before you start

• A modern web browser. The builder runs in the page, so no local install is described.
• A dataset in a tabular layout: one header row for series/labels, then one row per data point. Google Charts expects the first column to hold the category or label and subsequent columns to hold numeric values.
• A decision on chart type before you fine-tune styling, since available style options depend on the type you pick.

Step 1: Enter or update your dataset

The builder's input area holds the data that feeds the chart. Paste or type your table there, keeping the column structure consistent — a mismatched number of columns between rows is the most common reason a preview comes back empty.

If you are iterating, update the input data in place rather than starting over. The builder is designed for this: the source describes the workflow as trying to update input data and change the style of the chart, so repeated edits to the same dataset are the expected path.

Step 2: Choose a chart type and adjust style

Use the Customize control to set the chart type and its appearance. Because the builder is based on the Google Charts API, the styling options you see map to that API's chart options — titles, axis labels, colors, and legend behavior are the typical levers.

Practical order of operations:

1. Pick the chart type first (the shape of your data should drive this — categories over time suggest a line or column chart, part-to-whole suggests a pie).
2. Set labels and titles next, so you can read the preview while you style.
3. Adjust colors and legend last, once the data is rendering correctly.

Step 3: Preview at the right canvas size

The builder offers a set of preview dimensions rather than a single fixed canvas:

Switch between these before generating. A chart that looks balanced at 1200x1200 can crowd its labels at 320x240, and axis text is usually the first thing to collide at small sizes. Checking the smallest size you actually intend to use is the fastest way to catch that.

Step 4: Generate the chart

When the preview matches what you want, use Generate to produce the final chart. The output is a chart rendered through the Google Charts API from the data and options you set, so what you see in the preview at your chosen size is what the generated chart reflects. If you plan to reuse the chart, note the data and style settings you settled on — the builder does not describe a saved-project or account feature, so re-creating a chart means re-entering the same inputs.

Troubleshooting: blank preview or data not rendering

The two failures worth checking first are non-numeric values in data columns and inconsistent column counts between rows — between them they account for most cases where the builder accepts input but produces nothing visible.

When this approach fits

Use a Google Charts API-based builder like this one when you want a chart generated from a pasted table without writing chart code, and when you need control over the output canvas size. It suits one-off charts, quick data checks, and fixed-size embeds. If you need the chart to update automatically from a live data source, or you need to store and version many charts, a builder that generates a static result from manual input is the wrong tool — you would want the chart defined in code against your data source instead.

The Official UK Singles Chart and Official UK Albums Chart are compiled by the Official Charts Company (OCC) from a combination of paid sales, audio streaming, and video streaming, covering a defined seven-day chart week. To be eligible, a release generally must be commercially available in the UK, meet minimum length and format rules, and be sold or streamed through recognised retailers and services. Positions are ranked by a weighted "chart unit" total, and results are published weekly, with the Top 40 broadcast on BBC Radio 1.

What the Official UK Charts Actually Cover

The main charts are the Official Singles Chart Top 100 and the Official Albums Chart Top 100. Alongside them sit genre and format charts — Dance, Rock, Hip-Hop, Vinyl, Streaming, Country, Classical, Afrobeats and others — which use the same underlying data but filter it by genre or format.

The key distinction:

• Singles chart: tracks, typically individual songs or short releases.
• Albums chart: longer releases, including studio albums, compilations and some EPs.
• Genre/format charts: subsets of the above, not separate data collection systems.

How the Data Is Collected

The chart is built from three main consumption types:

Retailers and streaming services supply data to the OCC. Only recognised, legitimate outlets count — plays or sales from unauthorised sources do not.

The Chart Week

The chart week runs from Friday to Thursday. Data is collected across that window, processed, and the new chart is published the following Friday. The Top 40 is then broadcast on BBC Radio 1, which is why the "official" reveal is tied to that radio slot.

How Positions Are Calculated

Each release accumulates chart units. Sales, audio streams and video streams are combined using weightings set by the OCC, so that streaming and sales can be compared on one scale. The release with the highest unit total is Number 1, the next is Number 2, and so on down to 100.

Two practical points:

• Streaming is not counted one-to-one against a sale. A large number of streams is needed to equal one paid sale, which is why an act with heavy streaming but modest sales can still chart highly.
• Weightings can change. The OCC reviews its methodology periodically, so the exact conversion is not fixed forever. Treat any specific ratio you see quoted as potentially out of date.

Accelerated Chart Ratio (ACR)

A long-running rule affects how streams count for tracks that have been on the chart for a while. Under the Accelerated Chart Ratio, older charting tracks have their streaming points reduced relative to newer releases. This is designed to keep the chart responsive to new music rather than letting one huge hit sit at the top indefinitely. The exact thresholds and ratios are set by the OCC and can be revised.

What Makes a Release Eligible

Eligibility is about whether a release can appear on the chart at all. The main conditions:

Availability and Retail

• The release must be commercially available in the UK.
• It must be sold through recognised retailers and available on recognised streaming services.
• Free or promotional giveaways generally do not count as sales.

Length and Format Rules

• Singles must meet minimum and maximum length limits. A track that runs too long may be treated as an album track instead.
• Albums must meet a minimum length or track-count threshold to qualify as an album rather than a single or EP.
• Releases must be properly released, not leaked or unofficially distributed.

Pricing and Discounting

• Heavily discounted or free copies can be excluded or discounted from the count.
• Bundles that tie a sale to merchandise or tickets are restricted, to prevent chart positions being bought through bundling rather than genuine music consumption.

Artist and Credit Rules

• Chart credits follow the primary artist on the release.
• Featured artists are generally credited where they are formally billed, but the rules on how features are counted have been tightened over time to stop "feature stacking".

Multiple Versions

• Different versions of the same track (remixes, edits) are usually combined into one chart entry rather than charting separately.
• This prevents one song occupying several positions through variant releases.

How Genre and Format Charts Relate to the Main Charts

The genre and format charts are not separate competitions. They are views of the same data, filtered:

• A track can appear on the main Singles Chart and the Dance Chart at the same time.
• The Vinyl Chart reflects physical vinyl sales only.
• The Streaming Chart ranks by streaming consumption only.
• The Albums Chart and its genre variants work the same way.

So if you want to understand why a song is high on one chart and lower on another, the answer is usually the filter: the genre or format chart is showing only part of the total picture.

Practical Checklist: Will a Release Chart?

If you are trying to work out whether a release is eligible, run through this:

1. Is it commercially available in the UK through recognised outlets?
2. Does it meet the length/format rules for a single or album?
3. Is it priced normally, without a discount or bundle that would be excluded?
4. Are all versions combined into one entry?
5. Is the artist credit correct and within the feature rules?
6. Was it released within the Friday–Thursday chart week you are looking at?

If the answer to any of these is no, the release may be excluded, discounted, or treated as a different type of release.

Common Misunderstandings

• "One stream equals one sale." It does not. Streams are weighted and many are needed to match a sale.
• "The chart is based on sales only." Streaming is a major component of both singles and albums charts.
• "Any play counts." Only recognised services and legitimate consumption count.
• "Remixes chart separately." Versions are normally combined.
• "The chart week is Monday to Sunday." It is Friday to Thursday, with publication on Friday.

Where to See the Results

The full Official Singles and Albums Chart Top 100, plus the genre and format charts, are published by Official Charts. The Top 40 is broadcast on BBC Radio 1. For deeper data and professional tools, Official Charts also offers a Pro service, which is aimed at industry users rather than general listeners.

The exact weightings, ACR thresholds and eligibility limits are set and updated by the Official Charts Company, so for a specific release or a current rule, the authoritative source is the OCC's own published rules rather than any secondary summary.