# 1688 Scraper API: a hosted extraction endpoint for 1688 pages
> The oxylabs/1688-scraper repository is a thin documentation wrapper around a commercial extraction service rather than a library you install, and its whole mechanism is a single POST to a universal query endpoint with a source and a URL. What is worth reading is the response shape, the choice of HTML, parsed JSON or Markdown output, and the fact that the repository itself carries almost no code.
**oxylabs/1688-scraper** — The 1688 Scraper API is a powerful tool for extracting data from the 1688 e-commerce platform. It's ideal for e-commerce analytics, product comparison, and market research purposes.
- Repository: https://github.com/oxylabs/1688-scraper
- Website: https://oxylabs.io/products/scraper-api/ecommerce/1688?utm_source=github&utm_medium=repositories&utm_campaign=product
- Stars: 549 · Forks: 4
- Language: Java
- License: not declared
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/oxylabs-1688-scraper
## A repository that documents a service
The oxylabs/1688-scraper repository is not a scraper. The top level of the repository holds README.md and a single code examples/ directory, and the README is a brief guide that says as much: it showcases how the 1688 Scraper works, along with code examples.
What is being offered is a hosted service. The 1688 Scraper is described as part of the Web Scraper API, a real-time data gathering solution that uses a fast-adapting infrastructure for extracting 1688 product data, and it combines automated proxy management, web data access, and parsing to collect structured data from any public website at scale.
That last phrase, at scale, is the commercial proposition. The hard part of scraping a large Chinese B2B marketplace is not the request loop, it is the anti-bot measures, the residential proxy pool, the fact that 1688 renders much of its catalogue through JavaScript, and the fact that all of that changes without notice. A hosted service packages that problem as a monthly contract.
The repository itself is a marketing and documentation surface rather than an engineering artefact. The primary language recorded for it is Java, which is odd for a repository with no Java in it, and there are no GitHub releases, so the versioning of the service is not visible from the repository. The last push to the repository was on 2026-06-08, and the licence field records nothing at all, which is consistent with a repository that contains a README and example snippets rather than code you would vendor.
## One endpoint, a source name and a URL
The mechanism is described in one sentence: you can get 1688 results by providing your own URLs to the service, and it can return the HTML, parsed JSON, or Markdown output for any page you like.
The Python example in the README shows the whole call, and there is very little to it.
```python
import requests
from pprint import pprint
# Structure payload.
payload = {
'source': 'universal',
'url': 'https://fuzhuang.1688.com/nanzhuang?spm=a260k.dacugeneral.home2019category.2.663335e4bwa222'
}
```
Two fields carry the request. The source tells the service which scraper configuration to use, and here it is universal, which is the general-purpose one. The url is the page you want. Everything else, the request format, the retry behaviour, the proxy selection, the rendering, is on the service side.
The request itself is a POST to a single endpoint with basic authentication.
```python
# Get response.
response = requests.request(
'POST',
'https://realtime.oxylabs.io/v1/queries',
auth=('user', 'pass1'),
json=payload,
)
```
The credentials are a username and password tuple, which in the example are the placeholders user and pass1. This is the point at which a reader should note what kind of dependency they are taking on: your extraction runs against someone else's account, the authentication is theirs rather than a token you generate, and the request goes to a hostname whose DNS and TLS you do not control.
The comment in the example is also informative about the API design. It says that instead of a response with job status and results url, this will return the JSON response with the result, which means the endpoint has a synchronous convenience path for a single page. The job-and-status model is still there, since the response carries a job_id, and that is the shape a bulk extraction takes.
## The response envelope, and the timestamp fields
The output example in the README is a JSON document with a results array, and each entry describes one page.
```json
{
"results": [
{
"content": "\r\n\n\n\n\n \n ",
"created_at": "2025-02-20 12:15:04",
"updated_at": "2025-02-20 12:15:08",
"page": 1,
"url": "https://fuzhuang.1688.com/nanzhuang?spm=a260k.dacugeneral.home2019category.2.663335e4bwa222",
"job_id": "7165680254252520449",
"status_code": 200
}
]
}
```
The fields that matter for building a pipeline are the ones that are not the content. There is a page number, which tells you where you are in a paginated crawl and which lets you resume. There is a job_id, which is the handle for a batch and the thing you would use to check on a long extraction. There is a status_code, which is the upstream page's status rather than the service's, so a 200 here means the fetch succeeded even if the page you asked for does not contain what you wanted.
The created_at and updated_at fields are timestamps in a local-looking format rather than ISO 8601, and the gap between them in the example is four seconds, which is consistent with a request that was queued and then served. Their practical use is deduplication and freshness checking, and their practical annoyance is that a timestamp without a timezone is ambiguous.
The content field in this example is HTML, truncated in the documentation with an ellipsis, so the field is a string of whatever output mode was requested.
## HTML, parsed JSON, or Markdown, and what each one costs you
The three output modes are the most consequential choice in the API, and the README mentions them in a single clause.
HTML is the raw page as the service fetched it, rendered if rendering was needed. You get exactly what a browser would have got, and you own the parsing. That is the right choice when you need fields the service does not model, and it is the wrong choice when the site is a JavaScript application whose content is assembled from several API calls, because you then have to reimplement the extraction logic against a page that can change layout without notice.
Markdown is the page converted to a text representation. It strips the navigation, the scripts and the styling, which makes it far more compact than HTML and much more stable to diff across runs, and it is a reasonable intermediate format when you want to feed the content to a language model rather than to a parser, because a model handles Markdown better than it handles a page of divs.
Parsed JSON is the convenience option, and it is the one to think hardest about. The service's description says it combines automated proxy management, web data access, and parsing, so the parsing is part of the service. The consequence is that a field you need may not be among the fields it extracts, and when the site changes you find out from empty values rather than from a parse error. The alternative to relying on it is to take the HTML or Markdown and extract the fields yourself, which is more work but puts you in charge of the schema.
The README closes with the intended use: you can harvest public data from any 1688 web page, gather data such as price, reviews, or specific features, to monitor the market and outperform your competitors. Price and review extraction from a marketplace listing is a well-defined task with stable field names, which is the case where a vendor-hosted parser earns its cost.
## Where the code examples live, and what they do not cover
The README points to a code examples directory in the repository for other programming languages, and the URL is a branch path on github.com/oxylabs/1688-scraper. The Python snippet in the README is therefore the reference implementation, and the rest of the directory is the same call in other languages.
That is the entire code surface, and it is worth being clear about what a reader is and is not getting. There is no client library to install, no retry policy to configure, no connection pooling to tune, no local caching layer, and no test suite. Every behavioural decision is made by the parameters of the HTTP request, which means the API surface you depend on is the endpoint, the payload fields and the response envelope, three things that are documented in one README.
The other end of the product is the support relationship rather than the code. The README points to the Oxylabs Discord server, the YouTube channel, and says to connect with the support team through live chat or email support@oxylabs.io. The homepage for the product is on oxylabs.io under products/scraper-api/ecommerce/1688, with the README's link carrying campaign parameters, which tells you the repository is a marketing channel for the service rather than a community project.
The commercial terms are also elsewhere. The repository records no licence, so there is no grant of redistribution rights over the examples, and the per-request and subscription pricing is on the product page rather than in the documentation. For a team that intends to build on top of this, that is a normal arrangement, but it does mean the decision has a procurement component and not just a technical one.
## Where this approach is the wrong one
Three cases point elsewhere. The first is a team that needs extraction to run inside its own network or on its own cloud account. There is no self-hosted option here and no library, so the service is a hard dependency with your catalogue URLs and your credentials leaving your environment on every call. A team with a data residency requirement, or one that has been asked to justify every outbound connection to a vendor endpoint, has to look at a different kind of tool.
The second is a team that wants the raw 1688 marketplace data through a sanctioned channel. 1688 has an open platform and authorised partner programmes, and the commercial terms for scraping a marketplace are not something a scraper service can decide for you. A service that will happily fetch a page does not settle the question of whether you are permitted to use the result commercially, and the README's own framing of the use case is market monitoring and competitor comparison, which is a competitive-analysis activity rather than a resale activity.
The third is a small job. The service is priced and architected for volume, with proxy pools and a job model, and a one-off extraction of a few dozen listings is a case where writing the requests yourself against a proxy you control is cheaper and simpler than setting up an account.
The alternative worth weighing is a general-purpose scraping framework, Scrapy or Playwright driven by a script you maintain, which differs in approach on every axis that matters. You own the selectors, so a layout change breaks your code and you find out immediately, which is a liability and also the point, because a vendor parser that silently returns empty fields can feed bad numbers into a price-tracking system for a month before anyone checks. You also own the proxy costs, the block rate and the maintenance time, and the 1688 marketplace is exactly the kind of target where that maintenance is continuous. The hosted service trades control and monthly cost for not having to keep up with the anti-bot arms race, which is a good trade when extraction is a permanent part of your product and a bad one when it is a report you run once.
## Conclusion
The 1688 Scraper API fits a team that needs structured product data from 1688 and would rather pay for a hosted extraction service with proxy management than build and maintain a scraper for a marketplace with aggressive anti-bot measures. It does not fit a team that needs to run extraction on its own infrastructure or without a vendor relationship, because the repository ships no library and the endpoint is Oxylabs infrastructure. Before you adopt it, read the output mode you are paying for, since the same request returns HTML, parsed JSON or Markdown and the JSON option still puts a model or a parser in the loop, and check the pricing and retention terms on the product page, since the repository records no licence and no self-hosted option.
## FAQ
### What is the oxylabs/1688-scraper repository?
It is a documentation and example repository for the Oxylabs 1688 Scraper, which is part of the Web Scraper API, a hosted service that returns HTML, parsed JSON or Markdown for 1688 URLs. The repository itself holds only a README and a code examples directory, and the service is commercial.
### How do I call the 1688 Scraper API?
Send a POST to https://realtime.oxylabs.io/v1/queries with basic authentication, and a JSON payload containing a source and a url. The example uses source universal, which is the general-purpose configuration, and the response returns the result directly rather than a job status and results URL.
### What output formats does the 1688 Scraper support?
The README says the service can return the HTML, parsed JSON, or Markdown output for any page. The example response shows a results array where each entry carries a content field alongside page, url, job_id, status_code, created_at and updated_at.
### Do I need to install a library to use the 1688 Scraper?
No. The Python example uses the requests library directly with a POST call and a JSON payload. The repository provides code examples in other languages in its code examples directory, and there is no client package to install or configure.
### What data can I collect with the 1688 Scraper?
The README describes harvesting public data from any 1688 web page, and names price, reviews, and specific features as examples of the product data you can gather, for market monitoring and competitor comparison purposes. The service combines automated proxy management, web data access and parsing.
## Sources
- [Issues](https://github.com/oxylabs/1688-scraper/issues)
- [oxylabs/1688-scraper on GitHub](https://github.com/oxylabs/1688-scraper)
- [Project website](https://oxylabs.io/products/scraper-api/ecommerce/1688?utm_source=github&utm_medium=repositories&utm_campaign=product)
- [README](https://github.com/oxylabs/1688-scraper/blob/main/README.md)
---
Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/oxylabs-1688-scraper