Google Search Console provides a significant amount of information about how a website performs in search.
Clicks, impressions, click-through rates, average positions, queries, pages, countries, and devices are all available through its performance reports.
However, exporting this information often produces several CSV files containing hundreds or thousands of rows.
The challenge is no longer accessing the data. It is transforming separate datasets into a structured representation that makes patterns, changes, and potential opportunities easier to identify.
SEO Lens is a browser-based JavaScript utility developed by Palks Studio to process Google Search Console ZIP exports and generate structured analytical reports.
Its architecture relies on local file processing, dataset normalization, deterministic analysis, and client-side rendering.
1. General Architecture
The application operates entirely within the browser for its data processing and analysis.
The input is a ZIP archive exported from Google Search Console. The output is a visual report containing several analytical views.
The processing pipeline is organized as follows:
Google Search Console
β
βΌ
ZIP export
β
βΌ
Import
β
βΌ
Parser
β
βΌ
Normalization
β
βΌ
Analysis
β
βΌ
Insights / Prioritization
β
βΌ
Rendering
Each stage has a distinct responsibility.
| Layer | Responsibility |
|---|---|
| Import | Read the selected ZIP archive |
| Parser | Identify and parse CSV datasets |
| Normalization | Standardize filenames and columns |
| Analysis | Calculate metrics and identify signals |
| Prioritization | Organize findings for further review |
| Rendering | Display the structured report |
The separation between these stages prevents the analytical logic from depending directly on the original structure or language of the exported files.
No backend is required to process the archive or generate the report.
2. Reading a ZIP Archive in the Browser
Google Search Console can export performance data as a ZIP archive containing several CSV files.
A French export, for example, can contain the following files:
search-console-export.zip
βββ Graphique.csv
βββ RequΓͺtes.csv
βββ Pages.csv
βββ Pays.csv
βββ Appareils.csv
βββ Filtres.csv
Each file represents a different aspect of search performance.
| Dataset | Information |
|---|---|
| Graphique | Performance over time |
| RequΓͺtes | Search queries and metrics |
| Pages | Performance by page |
| Pays | Performance by country |
| Appareils | Performance by device |
| Filtres | Export filters and report scope |
The archive is opened directly in the browser, and its CSV files are identified before being passed to the parsing stage.
Browser File Access
JavaScript can access a file explicitly selected by the user through the browser's File API.
The following educational example illustrates how a selected file can be read into memory:
<input
type="file"
id="export-file"
accept=".zip"
>
const input = document.getElementById("export-file");
input.addEventListener("change", async () => {
const file = input.files[0];
if (!file) {
return;
}
const buffer = await file.arrayBuffer();
console.log("File size:", buffer.byteLength);
});
This example reads the selected file as binary data without transmitting it to a server.
It illustrates the browser file access mechanism rather than the exact implementation used by SEO Lens.
Reading the archive is only the first step. Its contents must then be extracted and interpreted before analysis can begin.
3. Parsing Multiple CSV Datasets
A ZIP export contains several datasets rather than a single table.
For example, a query dataset may contain rows such as:
Query,Clicks,Impressions,CTR,Position
python pdf comparison,25,1200,2.08%,8.4
javascript csv parser,12,850,1.41%,11.2
local data analysis,8,640,1.25%,6.8
A page dataset may instead contain:
Page,Clicks,Impressions,CTR,Position
https://example.com/article-a,35,1800,1.94%,7.5
https://example.com/article-b,18,950,1.89%,10.2
These examples use fictional data to illustrate the different dataset structures.
The parser must identify which dataset is being processed and extract the corresponding fields.
CSV Parsing Considerations
CSV parsing involves more than splitting a line at every comma.
Consider the following example:
Query,Clicks,Impressions
"python, javascript and data analysis",12,850
The first field contains a comma as part of its value.
A simple implementation such as:
const columns = line.split(",");
would incorrectly divide that query into multiple fields.
A CSV parser must account for quoted values, delimiters, and escaped characters.
Depending on the input format, it may also need to handle different line endings, encodings, or empty fields.
These are general requirements of reliable CSV processing. The exact parser implementation used by SEO Lens is not reproduced here.
4. Normalizing Localized Exports
One of the important implementation details is that Search Console exports can differ according to the interface language.
For example:
| English filename | French filename |
|---|---|
| Chart.csv | Graphique.csv |
| Queries.csv | RequΓͺtes.csv |
| Pages.csv | Pages.csv |
| Countries.csv | Pays.csv |
| Devices.csv | Appareils.csv |
| Filters.csv | Filtres.csv |
If the analysis layer depends directly on these filenames, supporting multiple languages can introduce duplicated processing logic.
SEO Lens uses aliases to identify equivalent datasets.
The normalization layer separates the original filenames and column labels from the internal analytical structure.
Queries.csv βββ
ββββΊ Query dataset
RequΓͺtes.csv βββ
Countries.csv ββ
ββββΊ Country dataset
Pays.csv ββ
Dataset Aliases
An educational example of an alias-based approach could be represented as follows:
const datasetAliases = {
"chart.csv": "performance",
"graphique.csv": "performance",
"queries.csv": "queries",
"requΓͺtes.csv": "queries",
"pages.csv": "pages",
"countries.csv": "countries",
"pays.csv": "countries",
"devices.csv": "devices",
"appareils.csv": "devices",
"filters.csv": "filters",
"filtres.csv": "filters"
};
function identifyDataset(filename) {
return datasetAliases[filename.toLowerCase()] ?? null;
}
Example:
identifyDataset("RequΓͺtes.csv");
// "queries"
identifyDataset("Queries.csv");
// "queries"
Both filenames resolve to the same internal dataset identifier.
This example illustrates the alias principle described in the application's architecture. It does not reproduce the exact source code.
Column Normalization
The same approach can be applied to CSV column names.
| French label | English label | Internal field |
|---|---|---|
| RequΓͺtes | Queries | query |
| Clics | Clicks | clicks |
| Impressions | Impressions | impressions |
| CTR | CTR | ctr |
| Position | Position | position |
Once normalized, a query record can be represented independently of the original language.
{
"query": "python pdf comparison",
"clicks": 25,
"impressions": 1200,
"ctr": 2.08,
"position": 8.4
}
This JSON object represents a conceptual normalized record rather than the exact internal schema used by SEO Lens.
The analytical layer can then work with consistent field names regardless of whether the original export was generated in French or English.
5. Normalizing Metric Values
Column names are not the only values that may require normalization.
Numeric representations can also differ between languages.
For example:
| Metric | Representation A | Representation B |
|---|---|---|
| Average position | 8.4 | 8,4 |
| CTR | 2.08% | 2,08% |
| Impressions | 1200 | 1200 |
These values must be interpreted correctly before being used in calculations.
In JavaScript, a value read from a CSV file is initially textual.
const rawValue = "8.4";
const position = Number(rawValue);
console.log(position);
// 8.4
However:
Number("8,4");
// NaN
A normalization layer must therefore account for the expected representation of numeric fields.
It must also distinguish between missing values and actual zero values.
For example, an empty CTR field should not automatically be interpreted as a measured CTR of zero.
These examples illustrate why normalization is an important stage between parsing and analysis. They do not establish the exact numeric conversion rules implemented by the utility.
6. Building a Performance Overview
The performance overview organizes the primary metrics available in a Search Console export.
| Metric | Meaning |
|---|---|
| Clicks | Recorded clicks from search |
| Impressions | Recorded search visibility |
| CTR | Clicks relative to impressions |
| Average position | Average recorded search position |
These metrics are related, but they do not describe the same aspect of performance.
A website may receive many impressions while generating relatively few clicks.
Another website may receive fewer impressions but achieve a higher click-through rate.
Calculating CTR
The click-through rate is calculated as:
CTR (%) = Clicks / Impressions Γ 100
For example:
Clicks : 125
Impressions : 10,000
CTR = 125 / 10,000 Γ 100
CTR = 1.25%
A simple educational JavaScript implementation is:
function calculateCTR(clicks, impressions) {
if (impressions <= 0) {
return null;
}
return (clicks / impressions) * 100;
}
The function returns null when no impressions are available, avoiding division by zero and distinguishing an undefined rate from an actual zero percent CTR.
Why Aggregation Matters
When several rows are combined, their CTR values should not necessarily be averaged directly.
Consider two queries:
| Query | Clicks | Impressions | CTR |
|---|---|---|---|
| Query A | 10 | 100 | 10.00% |
| Query B | 10 | 1000 | 1.00% |
| Total | 20 | 1100 | 1.82% |
A simple average of the two CTR values would produce:
(10% + 1%) / 2 = 5.5%
However, the combined CTR is:
20 / 1100 Γ 100 = 1.82%
The difference comes from the unequal number of impressions.
This is an important consideration when building analytical views from Search Console data.
The same principle also requires care when aggregating average positions. An unweighted average of row-level positions may not reproduce the position reported by Search Console.
These examples explain the analytical considerations involved in processing the data, rather than documenting the exact aggregation formulas used by SEO Lens.
7. Analyzing Performance Over Time
The chart dataset contains performance information across the selected reporting period.
This makes it possible to examine how clicks, impressions, CTR, and average position evolve.
A simplified dataset could look like this:
| Date | Clicks | Impressions | Position |
|---|---|---|---|
| 2026-08-01 | 12 | 850 | 9.4 |
| 2026-08-02 | 15 | 920 | 9.1 |
| 2026-08-03 | 11 | 780 | 9.6 |
| 2026-08-04 | 21 | 1200 | 8.7 |
The time-based view can help identify periods of increasing visibility, declining clicks, or changing average positions.
However, a change in one metric does not necessarily explain a change in another.
For example, impressions may increase because a website begins appearing for additional queries. If those queries rank lower or attract fewer clicks, the overall CTR may decrease.
This does not automatically indicate that the website's performance has deteriorated.
A useful report must therefore keep the underlying metrics visible rather than reducing every change to a positive or negative score.
8. Ranking Distribution
Average position provides a summary of search visibility, but it does not reveal how individual queries are distributed across ranking ranges.
Consider two datasets with similar average positions.
Dataset A:
Query 1 β Position 8
Query 2 β Position 9
Query 3 β Position 10
Dataset B:
Query 1 β Position 2
Query 2 β Position 9
Query 3 β Position 16
Both datasets have an arithmetic mean position of 9, but their distributions are different.
A ranking distribution view makes these differences easier to examine.
An illustrative grouping could be:
| Position range | Interpretation |
|---|---|
| 1β3 | Highest ranking positions |
| 4β10 | Other top-ten positions |
| 11β20 | Positions outside top ten |
| 21+ | Lower ranking positions |
These ranges are examples of how ranking data can be grouped. They are not presented as the exact thresholds implemented by SEO Lens.
The distribution can help identify whether visibility is concentrated among a small number of highly ranked queries or spread across a larger number of lower-ranked queries.
It also provides context for the opportunity analysis.
Importantly, Search Console reports average positions. A query with an average position of 8 does not necessarily appear at position 8 for every search.
9. Identifying SEO Opportunities
SEO Lens uses deterministic analysis to identify situations that may deserve further investigation.
One example is a query receiving significant impressions but relatively few clicks.
Another is a query already ranking within a range where additional investigation may be useful.
Consider the following fictional dataset:
| Query | Clicks | Impressions | CTR | Position |
|---|---|---|---|---|
| Query A | 15 | 2000 | 0.75% | 6.4 |
| Query B | 48 | 800 | 6.00% | 3.2 |
| Query C | 4 | 1100 | 0.36% | 12.8 |
These rows suggest different questions.
Query A receives substantial visibility and ranks relatively well, but its CTR is low.
Query B generates more clicks from fewer impressions.
Query C receives impressions despite ranking outside the top ten on average.
A deterministic analysis can organize these situations into signals for review.
Rule-Based Analysis
A conceptual rule can be expressed as:
IF impressions exceed a defined threshold
AND CTR is below a defined threshold
THEN identify the query for further review
The important distinction is that the rule identifies a pattern in the available data.
It does not explain why that pattern exists.
A low CTR may be influenced by:
- Search intent
- The page title or search snippet
- Competition
- Search result features
- The query's actual ranking distribution
- Differences between devices or countries
Search Console data alone cannot establish which explanation is correct.
The exact thresholds and prioritization rules used by SEO Lens are not specified here.
The purpose of the example is to illustrate deterministic analysis without introducing an artificial SEO score or an AI-generated interpretation.
10. Page Performance and Dataset Boundaries
The page dataset provides a different perspective from the query dataset.
Instead of organizing metrics around search terms, it organizes them around URLs.
Query dataset
βββ Performance by search query
Page dataset
βββ Performance by URL
A page-level view can help identify URLs receiving substantial impressions, generating clicks, or experiencing changes in visibility.
However, separate aggregated CSV files have an important limitation.
A query export and a page export do not necessarily establish which query generated impressions for which page.
Consider:
Queries.csv
Query A β 1000 impressions
Query B β 500 impressions
Pages.csv
Page A β 900 impressions
Page B β 600 impressions
These datasets do not provide enough information to reconstruct the exact relationship between each query and each page.
That relationship would require data containing both dimensions or a suitably filtered export.
The same limitation applies when attempting to connect individual queries with countries or devices using separate aggregated datasets.
An analytical report must therefore distinguish between information explicitly contained in the export and relationships that cannot be established from it.
11. Country and Device Analysis
The country and device datasets provide additional views of search performance.
For example:
| Country | Clicks | Impressions | CTR |
|---|---|---|---|
| France | 120 | 5000 | 2.40% |
| US | 35 | 4200 | 0.83% |
| UK | 18 | 1100 | 1.64% |
A device dataset might contain:
| Device | Clicks | Impressions | CTR |
|---|---|---|---|
| Desktop | 95 | 3200 | 2.97% |
| Mobile | 72 | 6800 | 1.06% |
| Tablet | 6 | 300 | 2.00% |
These views help identify differences in visibility and engagement across geographical areas and device categories.
For example, a lower mobile CTR may indicate a situation worth investigating.
However, it does not independently establish a mobile usability problem.
Likewise, a country generating substantial impressions but few clicks does not automatically indicate a translation or localization issue.
The data provides signals. Further investigation is required to determine their causes.
12. Diagnostic and Prioritization
SEO Lens organizes analytical results into diagnostic and priority views.
The objective is to make the information easier to review without hiding the original metrics behind a single numerical score.
The conceptual workflow is:
Normalized datasets
β
βΌ
Metric analysis
β
βΌ
Detected patterns
β
βΌ
Diagnostic observations
β
βΌ
Priorities for review
A diagnostic observation might identify a query with significant impressions and low CTR.
A priority view can then bring attention to that query alongside its original metrics.
This preserves the relationship between the observation and the data supporting it.
Why Avoid a Single SEO Score?
A numerical score such as:
SEO score: 87/100
would require a scoring model defining how different metrics are weighted and interpreted.
Without an explicit model, the score may hide more information than it reveals.
For example, increased impressions, reduced CTR, and improved average positions could occur during the same period.
Reducing these changes to one number would require assumptions about their relative importance.
SEO Lens instead keeps the available metrics visible and organizes the resulting observations into analytical views.
The report is intended to identify where further investigation may be useful, not to determine whether an entire website is objectively good or bad.
13. Client-Side Rendering
Once the analysis is complete, the report is rendered directly in the browser.
The application organizes the results into several views:
- Performance overview
- Performance evolution
- Ranking distribution
- Opportunities
- Page performance
- Countries and devices
- Diagnostic
- SEO priorities
The separation between analysis and rendering allows the application to distinguish the calculated information from its visual presentation.
CSV datasets
β
βΌ
Normalized records
β
βΌ
Analysis results
β
βββ Performance indicators
βββ Time-based views
βββ Ranking distribution
βββ Tables
βββ Diagnostic observations
This architecture also means that the presentation layer does not need to interpret the original localized CSV files directly.
The data has already been prepared before the report is displayed.
Rendering Imported Text Safely
Browser-based tools that process user-selected files must also consider how imported text is inserted into the page.
For example, a search query is data, not HTML.
An educational rendering example is:
function renderQuery(container, query) {
const element = document.createElement("p");
element.textContent = query;
container.appendChild(element);
}
Using textContent treats the imported value as text rather than interpreting it as HTML markup.
This is a general security consideration for client-side data processing. It is not a claim about the exact rendering implementation used by SEO Lens.
14. Local Processing and Privacy
SEO Lens performs its analysis locally in the browser.
User device
βββ Selected ZIP archive
βββ CSV extraction and parsing
βββ Normalization
βββ Analysis
βββ Visual report
The architecture does not require:
- A user account
- A Google API connection
- A remote database
- An AI service
- Uploading the Search Console export to Palks Studio
The selected archive is processed on the user's device.
This is particularly relevant because Search Console exports can contain information about a website's search visibility, queries, geographical audience, and page performance.
A server does not need access to these datasets if the required processing can be performed in the browser.
Local Processing and Network Activity
Client-side processing must be distinguished from a completely offline application.
A web application may still need to load its HTML, JavaScript, stylesheets, or other resources.
The relevant architectural distinction is that the imported Search Console data does not need to be transmitted to a backend for analysis.
Local data processing and the network requests required to load the application are separate concerns.
15. ZIP Exports vs. Direct API Integration
A direct integration with the Google Search Console API could remove the manual export step.
However, it would introduce additional architectural responsibilities.
| Aspect | ZIP-based approach | Direct API approach |
|---|---|---|
| Data import | Manual file selection | Programmatic requests |
| Google access | Existing export | Authorized API access |
| Authentication | Not required by tool | OAuth authorization |
| Token management | Not required | Required |
| Data freshness | Export date | API retrieval date |
The ZIP-based workflow relies on information that the user has already exported.
Google Search Console
β
βΌ
ZIP export
β
βΌ
SEO Lens
β
βΌ
Visual report
A direct API integration would require handling authorization, permissions, tokens, and API-specific constraints.
Depending on the architecture, it could also require additional backend infrastructure.
For this use case, the existing export provides the required input without introducing those dependencies.
The trade-off is explicit: one manual import step in exchange for a simpler processing architecture.
16. Scope and Limitations
SEO Lens analyzes the information contained in the provided Search Console export.
It does not perform:
- Website crawling
- Complete technical SEO audits
- Backlink analysis
- HTML content analysis
- Website modifications
- Direct Search Console synchronization
The report is therefore limited to the available datasets and the reporting period selected during export.
Search Console Data Is Not a Complete Website Inventory
A Search Console export does not necessarily contain every query, every URL, or every aspect of a website's search performance.
Exported data may be affected by reporting limits, privacy filtering, selected filters, and the way metrics are aggregated.
An analysis layer cannot reconstruct information that is absent from its input.
For example, a page missing from an export cannot automatically be classified as unindexed.
Likewise, the absence of a query does not prove that no user searched for it.
These distinctions are important when interpreting diagnostic results.
Signals Are Not Causes
The report can identify patterns such as:
High impressions + Low CTR
But establishing the cause may require additional investigation involving search results, page content, technical configuration, or indexing information.
The analysis should therefore remain connected to the data it actually receives.
Conclusion
SEO Lens illustrates a client-side approach to transforming Google Search Console exports into structured analytical information.
The architecture separates ZIP import, CSV parsing, localization normalization, deterministic analysis, prioritization, and visual rendering.
By keeping these responsibilities distinct, the application can organize several datasets without making its analytical logic depend directly on their original filenames or language.
The report preserves the underlying metrics rather than replacing them with an arbitrary SEO score.
Its limitations are equally important. Search Console exports provide useful performance information, but they cannot independently establish every cause of a ranking change, reconstruct missing relationships, or replace a complete technical SEO audit.
The objective is to make existing data easier to inspect while keeping the distinction between measured information, analytical signals, and conclusions that require further investigation.
Technical Documentation
The project's technical presentation and architecture documentation are available on GitHub.
View the SEO Lens technical resource

Top comments (2)
Nice Article!
Thanks. Glad you enjoyed the article and the approach behind SEO Lens.