MarketPulse Nigeria — AI Pricing & Market Saturation Agent

MarketPulse Nigeria tells a young Nigerian intending to start a small business the current cost of a product, and how saturated the market already is. By entering an item in the search field — e.g. "women's shoes", "okrika bale", "zobo" — the Actor returns a price band, the prices sellers cluster on, a market saturation score, and a concrete range to price within. This solution is for any Nigerian trying to start a small business from the comfort of their home.

It reads live listings from Jumia (formal retail) and Jiji (classifieds and secondhand), and returns both a structured dataset and a ready-to-read report. It runs on the Apify platform, so it can be scheduled, called from an API, or left running as a web dashboard.

What does MarketPulse Nigeria do?

A young Nigerian intending to start a small business in women jewellery would usually ask around, guess, and they either leave money on the table or price themselves out of a sale. Formal market data for African small business simply does not exist at this level.

MarketPlus Actor closes that gap. Given a plain-language description of a product, it:

1. Rewrites your words into terms the marketplaces can answer. This is not cosmetic. Searching Jumia for "bag of rice" returns storage containers — the words match the packaging, not the contents. Searching "rice" returns rice. "okrika bale" returns nothing on Jumia at all, because it is listed there as "thrift bale". Without this step the results are confidently wrong.
2. Collects live listings from both sides of the market — formal retail on Jumia, and the informal trade on Jiji where traders, thrift sellers and secondhand goods actually change hands.
3. Computes a price band — lowest, highest — after removing listings priced so far from the middle that they are clearly a different product or pack size.
4. Finds the prices sellers cluster on, which is often more useful than an average. For women's shoes on Jumia, 87% of listings sit between ₦7,000 and ₦9,000.
5. Compares retail against the informal market. Rice retails around ₦27,000 on Jumia and around ₦65,000 on Jiji, because Jiji is mostly full 50kg bags from traders. That gap is your margin.
6. Scores market saturation from 0–100, and shows the three inputs behind the number so you can judge it yourself.

Why use MarketPulse Nigeria?

• Price with evidence instead of guesswork. A concrete price range, drawn from listings that exist today.
• See how crowded a market is before you enter it. Fifty sellers on a commodity with tightly clustered prices is a very different business to fourteen sellers with a wide spread.
• See wholesale and retail side by side. The gap between what a thing costs on Jiji and what it sells for on Jumia is the single most actionable number for someone buying to resell.
• Spot the traps. Bulk and single units sit side by side in search results. The report flags this rather than quietly averaging a 50kg sack with a single sachet.
• Build on it. Every listing is pushed to a dataset you can export as JSON, CSV or Excel, or pull through the Apify API.

How to use MarketPulse Nigeria

1. Open the Input tab.
2. Type what you are pricing in What are you pricing? — everyday wording is fine.
3. Optionally set your location, which filters Jiji listings to your state, and raise Maximum listings for a wider sample.
4. Click Start.
5. Read the report on the run's Output tab, or browse every listing in the Dataset tab.

For repeat checks, set a Schedule and the Actor will track the same product over time.

Input

Field	Type	Default	Description
query (required)	string	—	What you're pricing, in plain language
location	string	—	Where you sell, e.g. "Mile 12, Lagos". Filters Jiji listings to that state; Jumia listings are national
country	enum	ng	Marketplace country: ng, ke, gh, eg (Jiji covers ng, ke, gh only)
platforms	array	["jumia","jiji"]	Sources to use: jumia, jiji, tiktok
maxResults	integer	60	Upper bound on listings collected (10–200)
agentMode	boolean	true	Reserved for the AI planner — see Roadmap
useProxy	boolean	true	Routes Jumia requests through Apify residential proxy. Required on the platform — Jumia blocks datacenter IPs
proxyGroups	array	["RESIDENTIAL"]	Which Apify Proxy groups to use
llmApiKey	secret	—	Optional Anthropic API key — see Roadmap

{
  "query": "okrika bale",
  "location": "Mile 12, Lagos",
  "country": "ng",
  "platforms": ["jumia", "jiji"],
  "maxResults": 60
}

Output

Every listing becomes one dataset row. Download as JSON, HTML, CSV or Excel.

{
  "platform": "jumia",
  "title": "Big Bull Rice 50Kg",
  "price": 75499.0,
  "currency": "NGN",
  "url": "https://www.jumia.com.ng/big-bull-rice-50kg-399018372.html",
  "seller_id": "479970",
  "brand": "Big Bull",
  "categories": ["Grocery", "Dried Beans, Grains & Rice", "Rice & Grains"],
  "rating": 4.1,
  "rating_count": 124,
  "is_sponsored": false,
  "region": null,
  "is_verified_seller": false,
  "source_query": "rice",
  "scraped_at": "2026-09-25T10:03:26Z"
}

The full report — price band, common price points, saturation score and verdict — is saved to the key-value store under OUTPUT, and to a shared store named market-pulse-reports so scheduled runs and the dashboard see the same cache.

Data fields

Field	Description
platform	Source marketplace — jumia, jiji or tiktok
title	Product name as listed
price / currency	Numeric price and ISO currency code
url	Direct link to the listing
seller_id	Seller identifier, used for the saturation score
brand	Brand, where the marketplace reports one
categories	Full category path
rating / rating_count	Average rating and number of reviews (Jumia)
region	Seller's state (Jiji)
is_verified_seller	Whether the marketplace has verified the seller (Jiji)
is_sponsored	Whether the listing was a paid placement
source_query	Which rewritten search term matched it
scraped_at	UTC timestamp of collection

Web dashboard (Standby mode)

The Actor also runs as an HTTP server, so a non-technical user never has to touch the Apify Console. Requests authenticate with Authorization: Bearer <APIFY_TOKEN> or ?token=<APIFY_TOKEN>.

Endpoint	Method	Description
/	GET	The dashboard. Also answers the platform readiness probe.
/api/market?q=…	GET	A market report. Serves from cache when one exists. Params: q (required), country, platforms, refresh.
/api/queries	GET	Every cached report, newest first.

curl "https://brendy--market-pulse-nigeria.apify.actor/api/market?q=okrika+bale&platforms=jumia,jiji" \
  -H "Authorization: Bearer $APIFY_TOKEN"

Open https://brendy--market-pulse-nigeria.apify.actor/?token=$APIFY_TOKEN in a browser for the dashboard itself.

Technologies

Layer	What is used
Runtime	Python 3.14 on apify/actor-python:3.14, packaged as a Docker image
Platform	Apify Actors, Datasets, Key-Value Stores, Standby mode, Schedules, Residential Proxy, pay-per-event billing
SDK / tooling	Apify SDK for Python 4.0.2, Apify CLI
Collection	curl_cffi 0.13.0 for browser TLS impersonation; Actor-to-Actor composition via piotrv1001/jiji-listings-scraper
Parsing	No browser and no HTML parser — Jumia's result set is read from the window.__STORE__ JSON blob embedded in its pages
Analysis	Pydantic 2.12.3 for typed contracts; Python statistics for quantiles; collections.Counter for price clustering
Web layer	FastAPI 0.121.1 + Uvicorn 0.38.0, OpenAPI 3.0.3 schema, single-file vanilla HTML/CSS/JS dashboard with light and dark themes
AI (inactive)	Anthropic SDK 0.75.0 targeting Claude Opus 5, using structured outputs and the tool runner — see Roadmap

Jumia needs no browser and no HTML parsing, so its compute cost is minimal; Jiji is billed by the upstream Store Actor at roughly $0.002 per listing. A 60-listing report across both sources takes about 20–40 seconds.

Roadmap — the AI agent layer

This is planned, not yet enabled. The Actor ships fully functional without it, and turns it on automatically once an Anthropic API key is configured (as ANTHROPIC_API_KEY on the Actor, or per-run via the llmApiKey input). The code for all three stages is in market_pulse/agent.py; what follows is what changes when a key is present.

1. Query planning becomes general instead of rule-based. Today an explicit rewriter handles the common failures — it translates Nigerian market vocabulary (okrika → thrift, tokunbo → used, derica → measuring cup), strips packaging words that would match the packaging itself, and drops over-specific size qualifiers. It works, but it only knows the terms written into it. The planner generalises to products and phrasings nobody enumerated.

2. agentMode becomes a real tool-calling loop. Rather than planning once, the agent would run searches as tools and re-query when results come back thin — so a query returning nothing triggers a second, broader attempt automatically instead of returning an empty report.

3. TikTok social commerce becomes available. This is the part that cannot be done any other way. Social sellers do not publish a price field; the number lives in the caption — "Available 💰35k DM to order". Reading it out requires a language model. The source is written and wired (market_pulse/sources/tiktok.py, calling the maintained clockworks/free-tiktok-scraper Actor), and returns nothing rather than guessing while no key is set.

4. The verdict gets written rather than composed. Today's verdict is assembled from the statistics by template — accurate, and honest about its limits, but flat. A model reading the same numbers can say which specific listings are dragging the range and what that means for this seller.

Until then, every number shown is computed deterministically from the raw listings and is reproducible from the dataset. That property is deliberate and will not change: the statistics are never produced by a language model, only interpreted by one.