Draw economics diagrams with an API

Create IB Economics diagrams (SL and HL) from JSON. The API returns a crisp SVG plus an edit link that opens the exact same graph in the web editor, where a person can adjust it and export PNG, SVG or PDF.

• Base URL: __ORIGIN__/api/v1
• No API key. CORS is enabled. Responses are deterministic, so cache freely.
• 88 templates covering all four units of the IB Economics syllabus, plus blank-axes for anything custom.

Quick start

# 1. Find a template (or browse the index at the end of this guide)
curl -s "__ORIGIN__/api/v1/templates?q=tariff"

# 2. Read its schema: params (types, options, ranges, defaults) and label keys
curl -s "__ORIGIN__/api/v1/templates/tariff"

# 3. Render it
curl -s "__ORIGIN__/api/v1/render" \
  -H "content-type: application/json" \
  -d '{"template":"tariff","params":{"lettering":"letters"},"title":"Figure 1: Effect of a tariff on steel imports","labels":{"main.d":"D_{steel}"},"style":{"palette":"color","areaLabels":"inside"}}'

The render response is JSON:

{
  "template": { "id": "tariff", "name": "Tariff" },
  "svg": "<?xml …><svg …>…</svg>",
  "width": 590, "height": 520,
  "editUrl": "__ORIGIN__/graph/tariff/#g=…",
  "svgUrl": "__ORIGIN__/api/v1/render.svg?spec=…",
  "labels": [{ "key": "main.d", "text": "D_{steel}", "hint": "Curve", "panel": "main" }],
  "stats": null,
  "warnings": []
}

• editUrl — give this to the person. It opens the graph in the editor, ready to tweak and export (PNG up to 4×, SVG, PDF, copy-to-clipboard).
• svgUrl — a stable GET URL for the image; usable in Markdown (![Figure 1](svgUrl)) or HTML <img>.
• svg — the image itself; save it as figure-1.svg.
• warnings — anything ignored or adjusted (unknown params, clamped numbers, unknown label keys). Read them and retry if needed.

For the image only, ask for SVG directly: POST /api/v1/render?format=svg or POST /api/v1/render.svg.

One-line GET form

Every param can go in the query string, which makes embeddable image URLs easy:

__ORIGIN__/api/v1/render/market-equilibrium.svg?pointLabel=true&style.palette=mono&title=Figure%201
__ORIGIN__/api/v1/render/demand-shift.svg?dir=dec&shift=2.5&label.d1=D_1
__ORIGIN__/api/v1/render/tariff.json?lettering=letters

Reserved query keys: title, style.<option>, label.<key>, hide=<key>,<key>, fonts=embed. Everything else is a template param. For the full spec in a GET request, use /api/v1/render.svg?spec=<URL-encoded JSON>.

Recommended workflow for AI agents

1. Choose a template from the index below (or GET /api/v1/templates?q=<words>). Prefer a specific template over blank-axes: templates compute intersections, welfare areas and cost curves correctly.
2. Read the schema (GET /api/v1/templates/{id}) to learn its params and labels keys. Labels depend on params (toggles add elements), so the render response also lists the labels actually drawn.
3. Render with POST /api/v1/render. Check warnings.
4. Deliver: share editUrl with the person (best: they can fine-tune and export), and/or save the SVG.
5. Need a PNG? The API returns SVG only. Convert locally (rsvg-convert -z 3 in.svg -o out.png, cairosvg, Inkscape, or a headless browser), or let the person open editUrl and use Export → PNG.

IB conventions worth following: label every curve (D, S, MSC, AD, SRAS…), label both axes, use subscripts for moved equilibria (P₁ → P₂), and give each figure a numbered title ("title": "Figure 1: …").

Endpoints

Graph spec

{
  "template": "tariff",               // required — a template id
  "params": { "lettering": "letters" }, // template options; see the template's schema
  "title": "Figure 1: …",             // optional; shown above the graph when set
  "labels": { "main.d": "D_{steel}" }, // replace any label's text by key
  "hidden": ["main.q3:x"],            // hide elements or labels by key
  "colors": { "main.s": "#008300" },  // recolour curves, areas, arrows, points
  "dashed": { "main.s": true },       // dash a curve or arrow
  "offsets": { "main.d": [8, -6] },   // nudge a label by [dx, dy] pixels
  "annotations": [ … ],               // draw extra lines, points, shading, arrows, text
  "style": { "palette": "mono" },     // look and feel, see below
  "format": "json",                   // "json" (default) or "svg"
  "embedFonts": false                 // true = embed the web font in the SVG (bigger file)
}

Keys for labels, hidden, colors, dashed and offsets

Keys come from the template schema (labels[].key and elements[].key):

• panel.element — a curve, area, arrow, point or text, e.g. main.d1
• panel.element:x / panel.element:y — a point's guide line and its axis label, e.g. main.e1:x (Q₁)
• panel:x / panel:y — axis titles; panel:title — a panel title; panel:origin — the "0"

In single-panel diagrams the panel prefix is optional: "d1" means "main.d1". Multi-panel templates (e.g. perfect-competition-short-run has industry and firm) need the full key.

Label text

Plain text with a tiny markup: P_1 → P₁, P_{max} → P with subscript "max", x^2 → superscript, \n → new line. Example: "S_1 = MPC", "P_{w} + t".

Annotations (draw anything)

Coordinates are data coordinates of the panel: by default x and y both run 0–10 with the origin at the bottom-left (each panel's xRange/yRange is in the schema; Lorenz curves use 0–100).

All kinds accept panel (default: the first panel) and color (#rrggbb). Up to 100 annotations.

Custom diagrams

For a diagram with no template, use blank-axes (params.axes: pq, macro, firm, labour, money, fx, phillips, ppc, time; params.numeric: true with xMax/yMax for a numbered scale) and draw it with annotations:

{
  "template": "blank-axes",
  "params": {
    "axes": "pq"
  },
  "title": "Figure 2: A subsidy on electric cars",
  "annotations": [
    {
      "kind": "line",
      "points": [
        [
          0,
          9
        ],
        [
          9,
          1.5
        ]
      ],
      "label": "D",
      "role": "demand"
    },
    {
      "kind": "line",
      "points": [
        [
          0,
          1.5
        ],
        [
          9,
          8.5
        ]
      ],
      "label": "S_1",
      "role": "supply"
    },
    {
      "kind": "line",
      "points": [
        [
          0,
          0.5
        ],
        [
          9,
          7.5
        ]
      ],
      "label": "S_2 = S_1 − subsidy",
      "role": "supply",
      "dashed": true
    },
    {
      "kind": "point",
      "at": [
        4.66,
        5.12
      ],
      "xLabel": "Q_1",
      "yLabel": "P_1"
    },
    {
      "kind": "point",
      "at": [
        5.28,
        4.6
      ],
      "xLabel": "Q_2",
      "yLabel": "P_2"
    },
    {
      "kind": "arrow",
      "from": [
        7.5,
        7.21
      ],
      "to": [
        7.5,
        6.45
      ],
      "label": "subsidy"
    },
    {
      "kind": "area",
      "points": [
        [
          0,
          9
        ],
        [
          0,
          5.12
        ],
        [
          4.66,
          5.12
        ]
      ],
      "role": "cs",
      "label": "CS"
    }
  ]
}

Compute intersection coordinates yourself so points and guides land exactly on the crossing.

Style

Errors

Errors are JSON with an HTTP status: { "error": { "code": "unknown_template", "message": "No template \"tarrif\". Did you mean: tariff, …?", "suggestions": [ … ] } }. Invalid enum values list the allowed options. Problems that can be worked around (unknown params or keys, out-of-range numbers) are returned as warnings instead of errors.

Limits

Request bodies up to 100 KB, text fields up to 200 characters, 100 annotations. The service is free; please cache results and avoid bulk generation.

Template index

Unit 1 · Introduction to economics

Production possibilities

• ppc-basic — Production possibilities curve (PPC): The maximum combinations of two goods an economy can produce with all resources fully and efficiently employed, with attainable, inefficient and unattainable points.
• ppc-shift — Shift of the PPC (economic growth or decline): An outward shift shows an increase in production possibilities (more or better resources, technology); an inward shift shows a loss of productive capacity.
• ppc-opportunity-cost — PPC and opportunity cost: Moving along the PPC, each extra unit of one good costs increasing amounts of the other (concave PPC) because resources are not equally suited to both uses.
• ppc-actual-potential-growth — Actual vs potential economic growth (PPC): Actual growth is a movement from inside the PPC towards it (using unemployed resources); potential growth is an outward shift of the PPC.

Unit 2 · Microeconomics

Demand & supply

• demand-curve — Demand curve (law of demand): A downward-sloping demand curve showing a movement along the curve after a price change.
• demand-shift — Shift in demand: An increase or decrease in demand caused by a non-price determinant, shifting the whole curve.
• supply-curve — Supply curve (law of supply): An upward-sloping supply curve showing a movement along the curve after a price change.
• supply-shift — Shift in supply: An increase or decrease in supply caused by a non-price determinant (costs, technology, taxes...).
• market-equilibrium — Market equilibrium: Demand and supply intersect at the market-clearing price and quantity.
• demand-change-equilibrium — Change in demand → new equilibrium: A shift in demand creates excess demand/supply at the old price, moving the market to a new equilibrium.
• supply-change-equilibrium — Change in supply → new equilibrium: A shift in supply creates excess demand/supply at the old price, moving the market to a new equilibrium.
• demand-supply-both-shift — Simultaneous shifts in demand and supply: Both curves shift at once; the effect on price or quantity depends on the relative size of the shifts.
• excess-demand-supply — Excess demand and excess supply: At a price above equilibrium there is a surplus; below it there is a shortage.
• consumer-producer-surplus — Consumer and producer surplus: Consumer surplus (above price, below demand) and producer surplus (below price, above supply) at equilibrium.
• allocative-efficiency — Allocative efficiency (MSB = MSC): Social surplus is maximised where marginal social benefit equals marginal social cost.

Elasticity

• ped-types — Price elasticity of demand: types: Demand curves for perfectly elastic, perfectly inelastic, unit elastic (rectangular hyperbola), relatively elastic and relatively inelastic demand.
• ped-linear-demand — PED along a straight-line demand curve: PED falls as we move down a linear demand curve: elastic above the midpoint, unit elastic at the midpoint, inelastic below. Total revenue peaks where PED = 1.
• ped-total-revenue — PED and total revenue: A price change on elastic demand moves total revenue the opposite way to price; on inelastic demand revenue moves the same way as price.
• pes-types — Price elasticity of supply: types: A straight supply curve through the origin is unit elastic; one cutting the price axis is elastic; one cutting the quantity axis is inelastic. Plus the perfectly elastic and inelastic extremes.
• commodity-price-volatility — Commodity price volatility (inelastic D and S): Primary commodities have price-inelastic demand and supply, so supply shocks (harvests, weather) cause large price swings with small quantity changes.

Government intervention

• indirect-tax-specific — Specific (per-unit) indirect tax: A per-unit tax shifts supply up by the amount of the tax: consumers pay more, producers receive less, the government earns revenue and there is a welfare loss.
• indirect-tax-ad-valorem — Ad valorem (percentage) indirect tax: A percentage tax (e.g. VAT/GST) pivots the supply curve upwards: the tax per unit grows as the price rises.
• tax-incidence-elasticity — Tax incidence and elasticity (comparison): The burden of an indirect tax falls mostly on whichever side of the market is more price inelastic.
• subsidy — Subsidy to producers: A per-unit subsidy shifts supply down by the subsidy: consumers pay less, producers receive more, output rises and the government pays the subsidy on every unit.
• price-ceiling — Price ceiling (maximum price): A maximum price set below equilibrium creates a shortage (excess demand), a welfare loss and the conditions for a parallel (black) market.
• price-floor — Price floor (minimum price): A minimum price set above equilibrium creates a surplus (excess supply); the government may buy the surplus, at a cost to taxpayers.
• minimum-wage — Minimum wage (labour market): A minimum wage above the equilibrium wage raises pay for those employed but creates unemployment: the quantity of labour supplied exceeds the quantity demanded.

Linear functions (HL)

• linear-demand-supply — Linear demand and supply functions (numeric) (HL): Plot Qd = a − bP and Qs = c + dP from real numbers, find equilibrium, and calculate surplus, tax revenue, subsidy cost, shortages and welfare loss.

Market failure

• negative-production-externality — Negative production externality: Production imposes external costs on third parties (e.g. pollution), so MSC lies above MPC and the free market over-produces: Q_m > Q*, creating a welfare loss.
• negative-consumption-externality — Negative consumption externality: Consumption imposes external costs on others (e.g. smoking, alcohol), so MSB lies below MPB and the free market over-consumes: Q_m > Q*, creating a welfare loss.
• positive-production-externality — Positive production externality: Production creates external benefits for third parties (e.g. worker training, R&D spillovers), so MSC lies below MPC and the free market under-produces: Q_m < Q*.
• positive-consumption-externality — Positive consumption externality: Consumption creates external benefits for others (e.g. education, vaccinations), so MSB lies above MPB and the free market under-consumes: Q_m < Q*.
• tradable-permits — Tradable permits (cap and trade): The government caps pollution with a fixed (vertical) supply of permits; the permit price is set by demand. Rising demand or a tighter cap raises the price, increasing the incentive to cut emissions.

Costs & revenues (HL)

• product-curves — Total, average and marginal product (HL): In the short run, total product rises at an increasing then decreasing rate. Marginal product peaks first (diminishing marginal returns set in), cuts average product at its maximum and is zero where total product is maximised.
• short-run-costs — Short-run cost curves (HL): Marginal cost cuts average variable cost and average total cost at their minimum points; the vertical gap between ATC and AVC is average fixed cost, which falls as output rises.
• long-run-average-cost — Long-run average cost (economies of scale) (HL): The LRAC curve falls with economies of scale, may be flat with constant returns to scale, and rises with diseconomies of scale. The lowest output at which LRAC is minimised is the minimum efficient scale.
• revenue-perfect-competition — Revenue curves in perfect competition (HL): A price-taking firm faces a perfectly elastic demand curve at the market price, so price = marginal revenue = average revenue and total revenue rises in a straight line.
• revenue-imperfect-competition — Revenue curves in imperfect competition (HL): With a downward-sloping demand (AR) curve, MR falls twice as fast. Demand is price elastic where MR > 0 and inelastic where MR < 0; total revenue is maximised where MR = 0 (unit elasticity).
• profit-maximisation — Profit maximisation (MC = MR) (HL): A firm maximises profit at the output where marginal cost equals marginal revenue (with MC rising). Below that output MR > MC, so producing more adds to profit; above it MC > MR.

Perfect competition (HL)

• perfect-competition-short-run — Perfect competition: short-run equilibrium (HL): The industry sets the price; the price-taking firm produces where MC = MR and may earn abnormal profit, normal profit or a loss in the short run.
• perfect-competition-long-run — Perfect competition: long-run adjustment (HL): Abnormal profit attracts entry (losses cause exit), shifting industry supply until price returns to minimum ATC and every firm earns normal profit.
• shut-down-break-even — Shut-down and break-even prices (HL): The short-run shut-down price is minimum AVC; the break-even price is minimum ATC. The firm’s short-run supply curve is its MC curve above AVC; in the long run it is MC above ATC.

Monopoly (HL)

• monopoly-profit — Monopoly: profit maximisation (HL): A monopolist produces where MC = MR and charges the price on the demand (AR) curve above that output. Barriers to entry let abnormal profit persist in the long run; a monopoly can also make normal profit or a loss.
• monopoly-welfare-loss — Monopoly vs perfect competition (welfare loss) (HL): Compared with a competitive industry (P = MC), a monopoly restricts output and raises price, creating a deadweight welfare loss and transferring consumer surplus to the producer.
• monopoly-revenue-maximisation — Revenue maximisation vs profit maximisation (HL): A profit maximiser produces where MC = MR; a revenue maximiser produces more, at a lower price, where MR = 0 (the unit-elastic point of the demand curve).
• natural-monopoly — Natural monopoly and regulation (HL): Huge economies of scale mean LRAC is still falling where it meets market demand, so one firm can supply the market most cheaply. Regulators may set P = AC (fair return, normal profit) or P = MC (allocatively efficient, but a loss that needs a subsidy).

Imperfect competition (HL)

• monopolistic-competition-short-run — Monopolistic competition: short run (HL): Product differentiation gives each firm a relatively elastic, downward-sloping demand curve. Producing where MC = MR, a firm can earn abnormal profit or make a loss in the short run.
• monopolistic-competition-long-run — Monopolistic competition: long run (HL): Free entry and exit shift each firm’s demand until it is tangent to ATC: only normal profit is earned. Output is below the level of minimum ATC (excess capacity), and P > MC.
• kinked-demand — Kinked demand curve (oligopoly) (HL): Rivals match price cuts but ignore price rises, so demand is elastic above the current price and inelastic below it. The kink creates a gap in MR, so MC can change within the gap without changing price or output (price rigidity).
• price-discrimination — Third-degree price discrimination (HL): A firm with market power separates customers into markets with different price elasticities and sets MR = MC in each: the higher price is charged in the market with the more inelastic demand.

Unit 3 · Macroeconomics

Economic activity

• business-cycle — Business cycle: Actual real GDP fluctuates around the long-term growth trend (potential output), moving through expansions, peaks, recessions and troughs.

AD/AS model

• ad-curve — Aggregate demand (AD) curve: AD slopes downward. A change in the average price level is a movement along AD; a change in C, I, G or (X − M) shifts the whole curve.
• sras-shift — Shift in short-run aggregate supply (SRAS): A change in costs of production (wages, raw materials, energy), business taxes or subsidies shifts SRAS, changing the price level and real output.
• ad-as-long-run-equilibrium — Long-run equilibrium (new classical / monetarist): In the new classical model the economy is in long-run equilibrium where AD and SRAS intersect on the vertical LRAS at potential output (Yp).
• keynesian-as — Keynesian aggregate supply curve: The Keynesian AS curve is horizontal when there is spare capacity, slopes upward as bottlenecks appear, and becomes vertical at full-employment output (Yfe).
• keynesian-ad-increase — Increase in AD in the Keynesian model: The effect of higher AD depends on where the economy is: output rises with no inflation in the horizontal range, both rise in the upward range, and only the price level rises at Yfe.
• recessionary-gap-nc — Recessionary (deflationary) gap — new classical: Short-run equilibrium below potential output. In the long run, falling wages shift SRAS right back to Yp; alternatively expansionary policy shifts AD right.
• inflationary-gap-nc — Inflationary gap — new classical: Short-run equilibrium beyond potential output. In the long run, rising wages shift SRAS left back to Yp; alternatively contractionary policy shifts AD left.
• recessionary-gap-keynesian — Recessionary (deflationary) gap — Keynesian: AD intersects the Keynesian AS below full-employment output; with sticky wages the economy can remain stuck there unless AD increases.
• inflationary-gap-keynesian — Inflationary gap — Keynesian: AD rises beyond the level needed for full employment; output cannot rise past Yfe so the excess demand only raises the price level.

Inflation & deflation

• demand-pull-inflation — Demand-pull inflation: An increase in AD pulls up the average price level (and, in the short run, real GDP).
• cost-push-inflation — Cost-push inflation (stagflation): Higher costs of production (e.g. oil prices, wages) shift SRAS left: the price level rises while real GDP falls — stagflation.
• deflation — Deflation: "good" vs "bad": "Good" deflation comes from rising aggregate supply (output rises); "bad" deflation comes from falling aggregate demand (output and employment fall).

Unemployment

• natural-rate-unemployment — Natural rate of unemployment: At the equilibrium real wage some of the labour force is still unemployed (frictional, structural and seasonal): the gap between the labour force (LF) and those willing and able to work at that wage (ASL).
• demand-deficient-unemployment — Demand-deficient (cyclical) unemployment: A fall in AD reduces real GDP below potential; firms need fewer workers and, with sticky wages, the demand for labour falls below the supply of labour.
• real-wage-unemployment — Real-wage (classical) unemployment: If the real wage is held above equilibrium (e.g. by a minimum wage or trade unions), the quantity of labour supplied exceeds the quantity demanded.
• structural-unemployment — Structural unemployment: Demand for labour falls in a declining industry. Workers who lack the skills (or mobility) to move into growing industries become structurally unemployed.

Phillips curve (HL)

• short-run-phillips-curve — Short-run Phillips curve (HL): The SRPC shows a short-run trade-off: lower unemployment comes with higher inflation. A supply shock shifts the SRPC outward (stagflation).
• long-run-phillips-curve — Long-run Phillips curve (expectations) (HL): Reducing unemployment below the natural rate (A → B) raises inflation; as expectations adjust the SRPC shifts up and unemployment returns to the NRU at higher inflation (B → C). The LRPC is vertical at the NRU.

Monetary & fiscal policy

• money-market — Money market (interest rate determination): The central bank fixes the money supply (vertical Sm). Equilibrium interest rate is where it meets money demand; increasing the money supply lowers the interest rate.
• ad-policy-shift — Fiscal or monetary policy shifting AD: Expansionary fiscal or monetary policy shifts AD right to close a recessionary gap; contractionary policy shifts AD left to close an inflationary gap.
• keynesian-multiplier — Keynesian multiplier (HL): An injection (e.g. ΔG) shifts AD by the initial amount, then successive rounds of induced spending shift it further: the final change in real GDP is k × ΔG, where k = 1/(1 − MPC).
• crowding-out — Crowding out (loanable funds): Government borrowing to fund a deficit raises demand for loanable funds, pushing up the real interest rate and reducing (crowding out) private investment.

Supply-side policies & growth

• economic-growth-adas — Economic growth (AD/AS): Long-term growth is an increase in potential output: LRAS (or the Keynesian AS) shifts right. If AD grows in step, real GDP rises without inflation.
• supply-side-policy — Supply-side policies: Market-based and interventionist supply-side policies raise productive capacity: LRAS shifts right, increasing potential output and putting downward pressure on the price level.

Inequality

• lorenz-curve — Lorenz curve and Gini coefficient: Plot real income-share data as a Lorenz curve. The Gini coefficient is the area between the line of equality and the Lorenz curve (A) divided by the total area under the line of equality (A + B).

Unit 4 · The global economy

International trade

• free-trade-importing — Free trade: importing country: When the world price is below the domestic equilibrium price, the country imports the difference between domestic demand and domestic supply. Consumers gain more than producers lose.
• free-trade-exporting — Free trade: exporting country: When the world price is above the domestic equilibrium price, domestic producers sell more and the surplus is exported. Producers gain more than consumers lose.
• comparative-advantage — Comparative advantage (PPCs) (HL): Two countries with straight-line PPCs and different opportunity costs. The country with the lower opportunity cost of a good has the comparative advantage in it; trade at terms between the two opportunity costs lets both consume beyond their PPCs.

Trade protection

• tariff — Tariff: A tariff raises the domestic price from P_w to P_w + t. Domestic production rises, consumption falls, imports shrink, the government collects revenue and two welfare-loss triangles appear.
• import-quota — Import quota: A quota limits imports to a fixed quantity, shifting domestic supply to S_dom + quota above the world price. The domestic price rises to P_q; holders of import licences/foreign exporters earn quota rent instead of the government earning revenue.
• production-subsidy-trade — Production subsidy (trade protection): A subsidy to domestic producers shifts domestic supply down by the subsidy. The price stays at P_w, so consumers are unaffected, but domestic output rises, imports fall, and the government pays the subsidy on every unit produced.
• export-subsidy — Export subsidy (HL): A per-unit subsidy on exports means producers will only sell at home for P_w + s, so the domestic price rises. Production and exports increase, domestic consumption falls, and the government pays the subsidy on every unit exported.

Exchange rates

• floating-exchange-rate — Floating exchange rate: The exchange rate is set by the demand for and supply of a currency on the foreign exchange market. A rise in demand or fall in supply appreciates the currency; a fall in demand or rise in supply depreciates it.
• fixed-exchange-rate — Fixed exchange rate (central bank intervention): To hold a peg, the central bank removes any excess supply or demand at the fixed rate: it buys its own currency (using foreign reserves) when there is downward pressure, and sells its own currency when there is upward pressure.
• managed-exchange-rate — Managed exchange rate (intervention band): In a managed float the currency moves freely within a band; the central bank intervenes only when market forces would push the rate beyond the upper or lower limit.

Balance of payments

• j-curve — J-curve (HL): After a depreciation the current account first worsens, because import and export volumes respond slowly (demand is price-inelastic in the short run), then improves once the Marshall–Lerner condition holds.

Build your own

Build your own

• blank-axes — Blank axes — draw your own: Empty axes for any diagram not in the library. Use “Draw your own” to add lines, curves, points with guides, shading, arrows and text.