# Map Chart Generator: Data to Choropleth & Bubble Maps (`jumblemog/map-chart-generator`) Actor Turn data into map images: values by country, US state or county, or province of any country as a choropleth, bubbles or categories, or coordinates as points. From JSON, CSV, a link or an Apify dataset to PNG, SVG, PDF or HTML. For AI agents. - **URL**: https://apify.com/jumblemog/map-chart-generator.md - **Developed by:** [Jumble Mog](https://apify.com/jumblemog) (community) - **Categories:** Developer tools, AI, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## Map Chart Generator: Data to Choropleth & Bubble Maps **Turn data into map images.** Give values by country, US state, US county or the provinces of any country, or places with latitude and longitude, and get back a clean, labeled map as **PNG, SVG, PDF, WebP, JPEG or an interactive HTML page** with a download link. Colored regions (choropleth maps), bubbles sized by value, category maps and point maps, with a legend, title and source line. The data can be a list of values, JSON rows, CSV, a link to a data file or Google Sheet, or the dataset of another Actor run, such as places from Google Maps. Region names are recognized in many spellings and 26 languages, and codes like `FR`, `FRA`, `TX` or a county's FIPS code work too. Made for people, automations and AI agents that need a map without a GIS tool. ![Four maps made by this Actor: US population by state as a blue choropleth with state codes and a Puerto Rico inset, India's states colored by their main official language with state names, the world's biggest cities as bubbles sized by population and colored by continent, and GDP per person by country on a dark theme](https://api.apify.com/v2/key-value-stores/Km5b4PG3kYHdZSb1E/records/map-chart-generator-examples.png?signature=1x59if8nEjmT9XPF82yAR) ### What it does - **Maps from region names**: 242 countries and territories, the 50 US states with DC and Puerto Rico, 3,230 US counties, and 4,596 states, provinces, prefectures and departments of 251 countries and territories (Bavaria, Ontario, Maharashtra, Île-de-France), plus 286 larger regions for 42 countries, such as France's 18 regions and Italy's 20. The map is picked from the names: country names give a world map, zoomed to the continent when all the data is there; state names a US map; `Cook County, IL` or `Harris, TX` a county map; and province names the provinces of their country. - **Names in any spelling**: names, ISO codes (`DE`, `DEU`, `276`), US postal and FIPS codes, local and older names (`Deutschland`, `Côte d'Ivoire`, `Burma`, `Swaziland`), World Bank style names (`Korea, Rep.`, `Egypt, Arab Rep.`), names in 26 languages (`Allemagne`, `德国`, `Россия`), and close misspellings, which are reported as guesses. Names that can't be matched are listed in the results, never dropped silently. - **Four kinds of map**: colored regions (choropleth) for rates and amounts, bubbles for totals, categories for text values (`{"Texas": "Open", "Ohio": "Coming soon"}`), and points from coordinates, sized and colored by any column. Places with coordinates can also be counted or added up per region, which turns a list of places into a map of where they are. - **Classes that read well**: tidy class breaks (quantiles, equal intervals, natural breaks or your own) or a smooth gradient, with 60 color schemes (single-hue, multi-hue, diverging around a midpoint, and categorical), your own colors, and a no-data color. Skewed data such as population gets classes automatically, so a few big regions don't wash out the rest. - **Labels that fit**: region names, codes, values or both, written only where they fit inside the region and don't overlap. US states get their two-letter codes by default. - **Zoom anywhere**: a continent, a part of the world (Middle East, Southeast Asia, Scandinavia, the Balkans, the European Union), a part of the US (New England, the Midwest, the Lower 48), a state (also on a county map) or a few countries. Far-away parts with data are drawn in insets, such as Puerto Rico next to the US or the overseas departments of France. The projection is picked for the area (Equal Earth for the world, Albers USA for the US, a conic projection turned to the area for countries), or choose one of 10, including a globe. - **Your own map**: a GeoJSON or TopoJSON file of sales territories, districts or ZIP code areas, matched to the data by name or ID. - **Seven formats**: PNG at 1x to 4x pixel density, SVG and PDF that stay sharp at any size, lossless WebP, JPEG, an interactive HTML page that shows each region's value on hover, and the Vega spec to embed in your own web pages. One charge per map, whatever the number of formats. - **Look**: light or dark theme, any background or water color, transparent PNGs, 13 fonts, value prefixes and suffixes (`$`, `%`), number formats and locales (`de-DE` writes 1.234,5), and Chinese, Japanese and Korean names. - **Facts with every map**: the map and projection used, the class breaks, the smallest and largest values, how many regions matched, and the names that weren't matched or were guessed, so an agent can check its map and fix its data. - **Image straight from the API**: the first map is also the run's `OUTPUT`, so the run-sync endpoint answers with the image itself. ### Who it's for - **AI agents and LLM apps** that answer "where" questions with a map: pass region names and numbers, and show the image in a chat, report or slide. The results list the names that didn't match, so the agent can correct them. - **Analysts, journalists and marketers** who need a clean choropleth for a report, article or deck without opening a GIS tool. - **Apify users** who want to see scraped data on a map: places from Google Maps as points or counted per county, prices by country, stores by state, job listings by region. - **Automation builders** in n8n, Make or Zapier who send a weekly map of sales by region to Slack or email. - **Developers** who need server-side map images without a browser, a map server or map tiles. ### How to use it 1. Put your data in **Values by region** (`{"France": 120, "Germany": 95}`), **Data rows**, **CSV data**, a **Data file link** or an **Apify dataset**. 2. Add a title, and pick colors, labels and where to zoom, or keep the defaults: the map, the columns and the colors are chosen from the data. 3. Click **Start**. The map appears in the **Output** tab with its download links. For many maps in one run, put them in **More maps**. You can also run it through the [Apify API](https://docs.apify.com/api/v2), on a schedule, or from Make, n8n, Zapier and other integrations. ### How-to examples Each example below is a complete input, checked with a run of the Actor. #### How to make a map of values by country (a choropleth) ```json {"values": {"France": 120, "Germany": 95, "Spain": 80, "Italy": 64, "Poland": 31, "Sweden": 18}, "title": "Stores by country", "labels": "namesAndValues"} ``` Result: a PNG map of Europe with the six countries shaded by value and their names and values written on them. The map zooms to the countries with data by itself, and all 6 names were matched (`"matchedRegions": 6`). #### How to make a US state map from a spreadsheet ```json {"csv": "state,sales\nCA,412\nTX,388\nNY,301\nFL,276\nWA,150\nIL,149", "map": "us-states", "title": "Sales by state", "valuePrefix": "$", "valueSuffix": "k"} ``` Result: the US states with Alaska and Hawaii moved in, the six states shaded and labeled, and a legend from $200k to $400k. State names, postal codes and FIPS codes all work, and so do counties by name and state or by FIPS code. #### How to plot places on a map, sized by a number ```json {"data": [{"name": "London", "lat": 51.5074, "lng": -0.1278, "orders": 120}, {"name": "Manchester", "lat": 53.4808, "lng": -2.2426, "orders": 60}, {"name": "Edinburgh", "lat": 55.9533, "lng": -3.1883, "orders": 45}, {"name": "Bristol", "lat": 51.4545, "lng": -2.5879, "orders": 38}], "sizeField": "orders", "labelField": "name", "title": "Orders by city"} ``` Result: a map of the United Kingdom (picked from where the points are) with a labeled circle per city, sized by orders. The results of a Google Maps scraper work as they are, with `datasetId`. #### How to let an AI agent draw maps Add this Actor to the [Apify MCP server](https://mcp.apify.com) with `https://mcp.apify.com/?tools=jumblemog/map-chart-generator`. The agent sends region names and values, or rows with coordinates, and shows the user `imageUrl`. Names it had to guess are listed in the result, so the agent can check them. ### FAQ **Which maps are there?** World countries, the provinces and states of every country, US states and US counties, with zooms to continents, regions such as the EU or Southeast Asia, and US regions such as the Lower 48. **Do I need map files or an API key?** No. The map data is built in, and you give names, codes or coordinates. **Can I get SVG or PDF?** Yes. `formats` takes PNG, SVG, PDF, WebP, JPEG, an interactive HTML page that shows values on hover, and the Vega spec. **Does it find addresses?** No. Points need latitude and longitude. Regions only need their names or codes. **Does it work with Zapier, Make or n8n?** Yes. Call the Actor with its Apify app or an HTTP request and send `imageUrl` to a report, email or Slack. ### Input | Field | What it does | | --- | --- | | `values` | Region names with their values, such as `{"France": 120, "Spain": 80}`. Text values color the regions by category. | | `data`, `csv`, `dataUrl`, `datasetId` | Rows as JSON, CSV or TSV text, a link to a public CSV, TSV or JSON file or Google Sheet (up to 30 MB), or an Apify dataset (up to 100,000 items). | | `map` | `auto` (default), `world`, `us-states`, `us-counties`, `provinces`, `regions`, `continents` or `custom`. | | `country` | The country for `provinces` or `regions`, such as `France`, `DE` or `JPN`. Detected from the names otherwise. | | `mapType` | `auto`, `choropleth` (colored regions), `bubble` or `points`. | | `focus` | Where to zoom: `Europe`, `Middle East`, `Scandinavia`, `New England`, `Texas`, or any countries or provinces. | | `projection` | `auto`, `equalEarth`, `naturalEarth1`, `mollweide`, `mercator`, `equirectangular`, `conicEqualArea`, `conicConformal`, `albersUsa`, `orthographic` (a globe) or `transverseMercator`. | | `aggregate` | How rows for the same region combine: `auto` (added up, and the latest year when there's a year or date column), `sum`, `mean`, `median`, `min`, `max`, `count`, `first` or `last`. | | `regionField`, `valueField` | The columns with the region names and the values. Found automatically by default; nested fields like `address.state` work. | | `latitudeField`, `longitudeField`, `sizeField`, `colorField`, `labelField` | For points: the coordinate columns (found automatically, including `location.lat`), and the columns that size, color and name them. | | `colorScheme`, `colors`, `reverseColors` | One of 60 schemes (`blues`, `viridis`, `redBlue`, `tableau10`...), or your own colors from low to high. | | `classification`, `classes`, `breaks` | `auto`, `continuous` (a gradient), `quantile`, `equal`, `jenks` or `custom`; the number of classes (5); your own class boundaries. | | `categoryColors`, `categoryOrder` | A color for each category, and their order in the legend. | | `domainMin`, `domainMax`, `midpoint`, `missingColor` | The ends of a gradient, the middle of a diverging scheme, and the color of regions without data. | | `title`, `subtitle`, `sourceNote`, `legendTitle` | The text on the map. The legend title defaults to the value column's name, made readable (`gdp_per_capita` becomes GDP per capita). | | `labels`, `labelSize`, `language` | `auto`, `none`, `names`, `values`, `namesAndValues` or `codes`; their size; and the language of the names (26 languages). | | `legend`, `valuePrefix`, `valueSuffix`, `valueFormat`, `locale` | The legend's place (`auto`, `bottom`, `right` or `none`) and how numbers look (`$`, `%`, `,.0f`, `de-DE`). | | `width`, `height`, `theme`, `font` | The size in CSS pixels (1,000 wide by default, with the height that the area's shape needs), `light` or `dark`, and one of 13 fonts. | | `backgroundColor`, `oceanColor`, `borderColor`, `borderWidth` | The background (or `transparent`), the water and the borders between regions. | | `bubbleColor`, `pointColor`, `maxBubbleSize`, `pointSize`, `opacity` | How bubbles and points look. | | `includeAntarctica` | Show Antarctica on world maps that have no data there. | | `geojson`, `geojsonUrl`, `geojsonKeyField` | Your own map as GeoJSON or TopoJSON, and the feature property with the names or codes the data uses. | | `formats`, `scale` | Any of `png` (default), `svg`, `pdf`, `webp`, `jpg`, `html` and `vega`, and the pixel density of PNG, WebP and JPEG (2 by default). | | `name`, `inlineImage`, `maps`, `maxMaps` | The files' name, the image as a base64 data URI in the results, more maps in one run, and the most maps per run (100). | The data, title, text and column settings in the form belong to the map in the form, and each entry in **More maps** (`maps`) is an object with its own. An entry without data maps the form's data, so one dataset can be drawn several ways in one run. The other settings (map, zoom, colors, labels, look and output) apply to every map unless an entry sets its own. The quickest map: values by country (the numbers here are an example): ```json { "values": {"France": 120, "Germany": 95, "Spain": 80, "Italy": 64, "Poland": 31, "Sweden": 18}, "title": "Stores by country", "labels": "namesAndValues" } ``` Places from a Google Maps scraper run, counted per US state: ```json { "datasetId": "YOUR_DATASET_ID", "mapType": "choropleth", "map": "us-states", "title": "Coffee shops by state", "legendTitle": "Places" } ``` The same places as points, sized by their number of reviews and colored by category: ```json { "datasetId": "YOUR_DATASET_ID", "sizeField": "reviewsCount", "colorField": "categoryName", "labelField": "title", "title": "Most reviewed places" } ``` US counties by FIPS code, zoomed to the Lower 48, as percentages: ```json { "csv": "fips,rate\n06037,5.1\n17031,4.8\n48201,4.4\n04013,3.9\n36047,5.6", "map": "us-counties", "focus": ["Lower 48"], "valueSuffix": "%", "title": "Unemployment rate by county" } ``` The provinces of a country, with names on the map: ```json { "values": {"Bavaria": 13.4, "North Rhine-Westphalia": 18.1, "Baden-Württemberg": 11.3, "Lower Saxony": 8.1, "Hesse": 6.4}, "title": "Population of German states", "subtitle": "Millions", "labels": "names", "colorScheme": "greens" } ``` Categories with their own colors: ```json { "values": {"Texas": "Open", "Ohio": "Open", "Florida": "Coming soon", "Oregon": "Coming soon", "Maine": "Closed"}, "categoryColors": {"Open": "#16a34a", "Coming soon": "#f59e0b", "Closed": "#9ca3af"}, "title": "Store status" } ``` Your own map of sales territories, from a GeoJSON file: ```json { "geojsonUrl": "https://example.com/territories.geojson", "geojsonKeyField": "territory", "values": {"North": 120, "South": 80, "East": 95, "West": 60}, "title": "Sales by territory" } ``` One dataset drawn three ways in one run: the places as points (the map in the form), the number of places per state, and their average rating per state: ```json { "datasetId": "YOUR_DATASET_ID", "title": "Places", "maps": [ {"title": "Places per state", "mapType": "choropleth", "map": "us-states"}, {"title": "Average rating per state", "mapType": "choropleth", "map": "us-states", "valueField": "totalScore", "aggregate": "mean"} ] } ``` ### Output Each map becomes one dataset item, and the files are saved in the run's key-value store: ```json { "index": 1, "name": null, "title": "US population by state", "status": "ok", "error": null, "imageUrl": "https://api.apify.com/v2/key-value-stores//records/001-US-population-by-state.png", "pngUrl": "https://api.apify.com/v2/key-value-stores//records/001-US-population-by-state.png", "svgUrl": null, "pdfUrl": null, "webpUrl": null, "jpgUrl": null, "htmlUrl": null, "vegaUrl": null, "map": "us-states", "mapName": "US states", "mapType": "choropleth", "projection": "albersUsa", "width": 2002, "height": 1644, "regionField": "state", "valueField": "population", "rows": 52, "matchedRegions": 52, "points": null, "unmatched": [], "guessed": [], "classification": "quantile", "breaks": [1.5, 3.3, 5.8, 10], "categories": null, "valueMin": 0.6, "valueMax": 39.5, "insets": ["Puerto Rico"], "sourceUrl": null, "notes": [], "processingSeconds": 1.1 } ``` Names that didn't match are listed in `unmatched` with how many rows had them, and spelling guesses in `guessed` (such as `{"input": "Germny", "matched": "Germany"}`). When a map can't be drawn, the item says why and isn't billed: ```json { "index": 2, "status": "failed", "error": "None of the names in 'product' (such as 'Widget A', 'Gadget B') were recognized as world countries. Check the map setting, or name the column with the regions in regionField.", "imageUrl": null } ``` Download your files within your plan's data retention period, or copy them to your own storage, because run storage expires. ### Pricing You pay per **map created**, at the price shown on this page, whatever the number of formats (PNG, SVG, PDF, WebP, JPEG, HTML and Vega files of the same map count once). Maps that can't be drawn are never charged. If you set a maximum cost per run, the Actor stops when the next map wouldn't fit. ### Speed One map usually takes about 4 seconds through the API, from request to image, most of it the run starting up. Each further map in the same run adds about 0.5 to 1.5 seconds as PNG, and a map of all 3,230 US counties in all seven formats takes about 5.5 seconds. The default 1 GB of memory is enough for most maps; give big batches or maps with many thousands of points 2 GB or more, which also brings more CPU. ### Tips and limits - County names need their state, because many repeat (31 counties and parishes are named Washington): write `Cook County, IL` or `Harris, TX`, add a state column, or use 5-digit FIPS codes. Names that fit more than one region are listed in `unmatched` with the candidates. - Province and country borders come from [Natural Earth](https://www.naturalearthdata.com) 5.1.2, which shows the boundaries in place on the ground; recent changes to provinces may be missing. For other borders, or smaller areas such as districts and ZIP codes, use your own GeoJSON map. - This draws regions and points on outline maps, not street maps or satellite images: a map covers at least a degree or two, so points in one city are shown on the outlines of their state or region. - Points: up to 20,000 per map, with labels for up to 30 points unless you choose a label column. Categories: the 19 most common get their own colors, and the rest are grouped as Other. - Data: up to 100,000 dataset items, and data and map files up to 30 MB. Each map has a 180-second limit. - Datasets: Apify lets this Actor read only the dataset picked in its **Apify dataset** field (`datasetId` at the top of the input), so maps in **More maps** can use that dataset but no other. To map several datasets, run once per dataset. - Data file links: CSV, TSV and JSON files, GitHub file links, and Google Sheets links (the sheet must be shared as "Anyone with the link" or published to the web). Every site's robots.txt is checked first, and its crawl delay kept. - SVG files keep their text as text, with common fallback fonts named, so it stays editable in Illustrator, Figma or Inkscape. ### For AI agents and developers This Actor works with the [Apify MCP server](https://mcp.apify.com), so AI agents can call it as a tool: pass region names and numbers in `values` (or rows in `data`), and read `imageUrl`, `unmatched` and `guessed` from the dataset item. For a direct API call that waits for the result: ```bash curl -X POST "https://api.apify.com/v2/acts/jumblemog~map-chart-generator/run-sync-get-dataset-items?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"values": {"Brazil": 3.1, "Argentina": 2.4, "Chile": 1.2, "Peru": 0.9, "Colombia": 1.8}, "title": "Orders by country"}' ``` To get the image itself as the response, call `run-sync` instead. It returns the run's `OUTPUT`, which is the first map (or the error as JSON): ```bash curl -X POST "https://api.apify.com/v2/acts/jumblemog~map-chart-generator/run-sync?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"values": {"California": 39.5, "Texas": 29.1, "Florida": 21.5, "New York": 20.2}, "labels": "codes"}' \ -o map.png ``` ### Credits - Map data: [Natural Earth](https://www.naturalearthdata.com) (public domain) for countries, provinces, regions and their names in many languages, and [US Atlas](https://github.com/topojson/us-atlas) (ISC license) for US states and counties, made from the US Census Bureau's cartographic boundary files (public domain). - Drawing: [Vega](https://vega.github.io/vega/) (BSD-3-Clause) through [vl-convert](https://github.com/vega/vl-convert) (BSD-3-Clause), [Shapely](https://github.com/shapely/shapely) and [NumPy](https://numpy.org) (BSD-3-Clause), [Pillow](https://python-pillow.org) (MIT-CMU) and [fontTools](https://github.com/fonttools/fonttools) (MIT). - Fonts (SIL Open Font License): Inter, Roboto, Open Sans, Lato, Montserrat, Poppins, Source Sans 3, Noto Sans, IBM Plex Sans, Nunito, Arimo (drawn for Arial), Noto Serif and JetBrains Mono from Google Fonts, and Noto Sans CJK. - Example data in the picture above: US Census Bureau (2020 census), UN World Urbanization Prospects 2018 (approximate city populations), and World Bank GDP figures as published in Natural Earth. - This Actor isn't affiliated with Natural Earth, the US Census Bureau, Vega or the projects above. # Actor input Schema ## `data` (type: `array`): Rows as JSON objects, like the items of a scraper's dataset: \[{"country": "France", "sales": 120}, ...]. Each row names a region (a country, US state or county, or a province) and has a value, or has latitude and longitude for a point. The columns are found automatically; you can name them in Columns below. Nested fields work with dots, such as location.lat. ## `values` (type: `object`): The quickest way to give data: region names with their values, such as {"France": 120, "Germany": 95, "Spain": 80}. Values can also be text, which colors the regions by category, such as {"Texas": "Republican", "California": "Democrat"}. ## `csv` (type: `string`): CSV or TSV text with a header row, such as country,sales. Numbers like $1,200 and 45% are understood. ## `datasetId` (type: `string`): A dataset in your Apify account, such as the results of a Google Maps scraper run, to map its items (its ID or name). Places with coordinates become points, or are counted per region with Map type set to colored regions. Up to 100,000 items are read. The tool gets read access to this dataset only. ## `dataUrl` (type: `string`): A link to a public CSV, TSV or JSON file (up to 30 MB), a GitHub file, or a Google Sheet shared as "Anyone with the link". The site's robots.txt is respected. ## `map` (type: `string`): Which regions the names are. Detected from the data: country names give a world map (zoomed to a continent when all the data is there), US state names a US map, county names a county map, and province names (Bavaria, Ontario, Maharashtra...) the provinces of their country. ## `country` (type: `string`): The country whose provinces or regions to map, by name or code, such as France, DE or JPN. Only needed when Map is set to provinces or regions; detected otherwise. ## `mapType` (type: `string`): Colored regions show a value per region; bubbles show amounts as circles; points show places from their coordinates. Rows with coordinates and Map type set to colored regions are counted (or added up) per region. ## `focus` (type: `array`): Parts of the world or regions to zoom to: a continent (Europe, Africa), a part of the world (Middle East, Southeast Asia, Scandinavia, Balkans, Latin America, Sub-Saharan Africa, European Union), countries, a part of the US (New England, Midwest, West Coast, Lower 48), states (Texas, also on county maps) or provinces. Default: the whole map, or the area with data. ## `projection` (type: `string`): How the round earth is drawn flat. Auto uses Equal Earth for the world, Albers USA for the US, and a conic projection turned to the area for countries and continents. ## `aggregate` (type: `string`): How to combine several rows for one region, such as many orders per state. Rows with a year or date column show the latest year per region. ## `regionField` (type: `string`): The column with the region names or codes. Default: found automatically. ## `valueField` (type: `string`): The column with the values to color by (numbers, or text for categories). Default: the first number column; with none, rows are counted per region. ## `latitudeField` (type: `string`): For points: the latitude column, such as lat or location.lat. Default: found automatically. ## `longitudeField` (type: `string`): For points: the longitude column, such as lng, lon or location.lng. ## `sizeField` (type: `string`): For points: a number column that sizes each point as a bubble, such as reviewsCount or population. ## `colorField` (type: `string`): For points: a column that colors them, by category (such as categoryName) or by number (such as totalScore). ## `labelField` (type: `string`): For points: the column with the names to write next to them. Default: title, name or city when there are up to 30 points. ## `colorScheme` (type: `string`): Colors for the values. Single-hue and multi-hue schemes for amounts, diverging schemes for values around a middle (such as change, + and -), and category schemes for text values. ## `classification` (type: `string`): A smooth gradient, or classes with tidy boundaries such as 1.5, 3 and 10. ## `classes` (type: `integer`): How many color classes for quantiles, equal intervals and natural breaks. ## `breaks` (type: `array`): Your own class boundaries, such as \[10, 20, 50, 100] for five classes: under 10, 10 to 20, 20 to 50, 50 to 100 and 100 or more. ## `colors` (type: `array`): Your own colors, used instead of the scheme: from low to high for numbers (two or more, blended), or one per category in order. Any CSS color, such as #f7fbff or navy. ## `categoryColors` (type: `object`): A color for each category, such as {"Yes": "#16a34a", "No": "#dc2626"}. ## `categoryOrder` (type: `array`): The order of the categories in the legend. Default: the most common first. ## `reverseColors` (type: `boolean`): Turn the scheme around, such as dark for low values. ## `domainMin` (type: `number`): For a smooth gradient: the value that gets the lightest color (lower values get it too). Default: the smallest value. ## `domainMax` (type: `number`): For a smooth gradient: the value that gets the darkest color. Default: the largest value. ## `midpoint` (type: `number`): For diverging schemes: the value in the middle of the colors, such as 0 or 50. Default: 0 when the values cross zero. ## `missingColor` (type: `string`): The color of regions without data. Default: light gray. ## `title` (type: `string`): The map's title, at the top left. ## `subtitle` (type: `string`): A smaller line under the title, such as the unit or the year. ## `sourceNote` (type: `string`): A small line at the bottom, such as the data source. ## `labels` (type: `string`): What to write on the regions. Labels are only drawn where they fit inside a region and don't overlap. ## `language` (type: `string`): The language of the names on the map and in the results, where the map data has them (all countries, most provinces). ## `legend` (type: `string`): Where the color key goes. ## `legendTitle` (type: `string`): The title over the color key. Default: the value column's name, made readable (gdp_per_capita becomes GDP per capita). ## `valuePrefix` (type: `string`): Put before every number in the legend and labels, such as $. ## `valueSuffix` (type: `string`): Put after every number, such as %, M or " km²" (with its space). ## `valueFormat` (type: `string`): A d3 number format for the legend and labels, such as ,.0f (1,234), .1f (12.3), .0% (45%, for values like 0.45), $,.2f or .3~s (1.23M). Default: chosen from the values. ## `locale` (type: `string`): Thousands and decimal separators, such as en-US (1,234.5), de-DE (1.234,5) or fr-FR (1 234,5). ## `labelSize` (type: `number`): Font size of the labels on the map. Default: 11 px at a width of 1,000 px, scaled with the width. ## `width` (type: `integer`): Map width in CSS pixels. PNG files are this times the pixel scale (2,000 px wide by default). The height follows the shape of the area. ## `height` (type: `integer`): A fixed height. Default: what the area's shape needs, so there's no empty space. ## `theme` (type: `string`): Light or dark background and text. ## `font` (type: `string`): The font for all text. Chinese, Japanese and Korean names always work. ## `backgroundColor` (type: `string`): Any CSS color, or transparent for a PNG or WebP without a background. Default: white, or dark gray with the dark theme. ## `oceanColor` (type: `string`): A color for the sea behind the land, such as #dbeafe. Default: none (the background). ## `borderColor` (type: `string`): The color of the lines between regions. Default: the background color. ## `borderWidth` (type: `number`): The width of the lines between regions. Default: thinner for many small regions. ## `bubbleColor` (type: `string`): The color of the bubbles on bubble maps. Default: #e45756 (red). ## `pointColor` (type: `string`): The color of points that aren't colored by a column. Default: #2563eb (blue). ## `maxBubbleSize` (type: `number`): The diameter of the biggest bubble. Default: 7% of the width. ## `pointSize` (type: `number`): The diameter of points without a size column. Default: smaller when there are many. ## `opacity` (type: `number`): From 0.05 (see-through) to 1 (solid). Default: 0.72 for bubbles, 0.85 for points. ## `includeAntarctica` (type: `boolean`): Antarctica is left off world maps unless it has data or this is on. ## `geojson` (type: `object`): Your own map: a GeoJSON FeatureCollection of polygons (such as sales territories, districts or ZIP code areas) or a TopoJSON topology. The data's region names are matched to the features' names (or the property in Feature name property). With no data, the values come from the features' properties. ## `geojsonUrl` (type: `string`): A link to a public GeoJSON or TopoJSON file (up to 30 MB) instead. ## `geojsonKeyField` (type: `string`): The property of the features that holds the names or codes the data uses, such as NAME or GEOID. Default: name, NAME, id or code. ## `formats` (type: `array`): PNG for chats, emails, docs and slides; SVG and PDF are vector files that stay sharp at any size; WebP is small and lossless; HTML is an interactive page with values on hover; the Vega spec can be embedded in web pages with vega-embed. One charge per map, whatever the number of formats. ## `scale` (type: `number`): Pixel density of PNG, WebP and JPEG files: 2 (default) is sharp on high-resolution screens, 1 gives smaller files, 3 or 4 for print. ## `name` (type: `string`): A name for the map's files and dataset row. Default: the title or the map's name. ## `inlineImage` (type: `boolean`): Also put each image in its dataset row as a base64 data URI, for emails and HTML that can't load links. Images up to 2 MB. ## `maps` (type: `array`): More maps in one run. Each entry is an object with its own data and settings, such as {"values": {"France": 3, "Spain": 5}, "title": "Stores"} or {"valueField": "profit", "colorScheme": "greens"}. An entry without data maps the data given above, so one dataset can be drawn several ways. Settings left out come from this form. ## `maxMaps` (type: `integer`): Stop after this many maps, so the cost of a run stays predictable. ## Actor input object example ```json { "data": [ { "state": "California", "population": 39.5 }, { "state": "Texas", "population": 29.1 }, { "state": "Florida", "population": 21.5 }, { "state": "New York", "population": 20.2 }, { "state": "Pennsylvania", "population": 13 }, { "state": "Illinois", "population": 12.8 }, { "state": "Ohio", "population": 11.8 }, { "state": "Georgia", "population": 10.7 }, { "state": "North Carolina", "population": 10.4 }, { "state": "Michigan", "population": 10.1 }, { "state": "New Jersey", "population": 9.3 }, { "state": "Virginia", "population": 8.6 }, { "state": "Washington", "population": 7.7 }, { "state": "Arizona", "population": 7.2 }, { "state": "Massachusetts", "population": 7 }, { "state": "Tennessee", "population": 6.9 }, { "state": "Indiana", "population": 6.8 }, { "state": "Maryland", "population": 6.2 }, { "state": "Missouri", "population": 6.2 }, { "state": "Wisconsin", "population": 5.9 }, { "state": "Colorado", "population": 5.8 }, { "state": "Minnesota", "population": 5.7 }, { "state": "South Carolina", "population": 5.1 }, { "state": "Alabama", "population": 5 }, { "state": "Louisiana", "population": 4.7 }, { "state": "Kentucky", "population": 4.5 }, { "state": "Oregon", "population": 4.2 }, { "state": "Oklahoma", "population": 4 }, { "state": "Connecticut", "population": 3.6 }, { "state": "Utah", "population": 3.3 }, { "state": "Iowa", "population": 3.2 }, { "state": "Nevada", "population": 3.1 }, { "state": "Arkansas", "population": 3 }, { "state": "Mississippi", "population": 3 }, { "state": "Kansas", "population": 2.9 }, { "state": "New Mexico", "population": 2.1 }, { "state": "Nebraska", "population": 2 }, { "state": "Idaho", "population": 1.8 }, { "state": "West Virginia", "population": 1.8 }, { "state": "Hawaii", "population": 1.5 }, { "state": "New Hampshire", "population": 1.4 }, { "state": "Maine", "population": 1.4 }, { "state": "Rhode Island", "population": 1.1 }, { "state": "Montana", "population": 1.1 }, { "state": "Delaware", "population": 1 }, { "state": "South Dakota", "population": 0.9 }, { "state": "North Dakota", "population": 0.8 }, { "state": "Alaska", "population": 0.7 }, { "state": "District of Columbia", "population": 0.7 }, { "state": "Vermont", "population": 0.6 }, { "state": "Wyoming", "population": 0.6 }, { "state": "Puerto Rico", "population": 3.3 } ], "map": "auto", "mapType": "auto", "projection": "auto", "aggregate": "auto", "colorScheme": "auto", "classification": "auto", "classes": 5, "reverseColors": false, "title": "US population by state", "subtitle": "2020 census, millions of people", "sourceNote": "Source: US Census Bureau", "labels": "auto", "language": "en", "legend": "auto", "locale": "en-US", "width": 1000, "theme": "light", "font": "Inter", "includeAntarctica": false, "formats": [ "png" ], "scale": 2, "inlineImage": false, "maxMaps": 100 } ``` # Actor output Schema ## `results` (type: `string`): One item per map: image links, the map used, matched and unmatched names, classes, or the error. ## `files` (type: `string`): The PNG, SVG, PDF, WebP, JPEG, HTML and Vega files saved in the run's key-value store. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "data": [ { "state": "California", "population": 39.5 }, { "state": "Texas", "population": 29.1 }, { "state": "Florida", "population": 21.5 }, { "state": "New York", "population": 20.2 }, { "state": "Pennsylvania", "population": 13 }, { "state": "Illinois", "population": 12.8 }, { "state": "Ohio", "population": 11.8 }, { "state": "Georgia", "population": 10.7 }, { "state": "North Carolina", "population": 10.4 }, { "state": "Michigan", "population": 10.1 }, { "state": "New Jersey", "population": 9.3 }, { "state": "Virginia", "population": 8.6 }, { "state": "Washington", "population": 7.7 }, { "state": "Arizona", "population": 7.2 }, { "state": "Massachusetts", "population": 7 }, { "state": "Tennessee", "population": 6.9 }, { "state": "Indiana", "population": 6.8 }, { "state": "Maryland", "population": 6.2 }, { "state": "Missouri", "population": 6.2 }, { "state": "Wisconsin", "population": 5.9 }, { "state": "Colorado", "population": 5.8 }, { "state": "Minnesota", "population": 5.7 }, { "state": "South Carolina", "population": 5.1 }, { "state": "Alabama", "population": 5 }, { "state": "Louisiana", "population": 4.7 }, { "state": "Kentucky", "population": 4.5 }, { "state": "Oregon", "population": 4.2 }, { "state": "Oklahoma", "population": 4 }, { "state": "Connecticut", "population": 3.6 }, { "state": "Utah", "population": 3.3 }, { "state": "Iowa", "population": 3.2 }, { "state": "Nevada", "population": 3.1 }, { "state": "Arkansas", "population": 3 }, { "state": "Mississippi", "population": 3 }, { "state": "Kansas", "population": 2.9 }, { "state": "New Mexico", "population": 2.1 }, { "state": "Nebraska", "population": 2 }, { "state": "Idaho", "population": 1.8 }, { "state": "West Virginia", "population": 1.8 }, { "state": "Hawaii", "population": 1.5 }, { "state": "New Hampshire", "population": 1.4 }, { "state": "Maine", "population": 1.4 }, { "state": "Rhode Island", "population": 1.1 }, { "state": "Montana", "population": 1.1 }, { "state": "Delaware", "population": 1 }, { "state": "South Dakota", "population": 0.9 }, { "state": "North Dakota", "population": 0.8 }, { "state": "Alaska", "population": 0.7 }, { "state": "District of Columbia", "population": 0.7 }, { "state": "Vermont", "population": 0.6 }, { "state": "Wyoming", "population": 0.6 }, { "state": "Puerto Rico", "population": 3.3 } ], "title": "US population by state", "subtitle": "2020 census, millions of people", "sourceNote": "Source: US Census Bureau" }; // Run the Actor and wait for it to finish const run = await client.actor("jumblemog/map-chart-generator").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "data": [ { "state": "California", "population": 39.5, }, { "state": "Texas", "population": 29.1, }, { "state": "Florida", "population": 21.5, }, { "state": "New York", "population": 20.2, }, { "state": "Pennsylvania", "population": 13, }, { "state": "Illinois", "population": 12.8, }, { "state": "Ohio", "population": 11.8, }, { "state": "Georgia", "population": 10.7, }, { "state": "North Carolina", "population": 10.4, }, { "state": "Michigan", "population": 10.1, }, { "state": "New Jersey", "population": 9.3, }, { "state": "Virginia", "population": 8.6, }, { "state": "Washington", "population": 7.7, }, { "state": "Arizona", "population": 7.2, }, { "state": "Massachusetts", "population": 7, }, { "state": "Tennessee", "population": 6.9, }, { "state": "Indiana", "population": 6.8, }, { "state": "Maryland", "population": 6.2, }, { "state": "Missouri", "population": 6.2, }, { "state": "Wisconsin", "population": 5.9, }, { "state": "Colorado", "population": 5.8, }, { "state": "Minnesota", "population": 5.7, }, { "state": "South Carolina", "population": 5.1, }, { "state": "Alabama", "population": 5, }, { "state": "Louisiana", "population": 4.7, }, { "state": "Kentucky", "population": 4.5, }, { "state": "Oregon", "population": 4.2, }, { "state": "Oklahoma", "population": 4, }, { "state": "Connecticut", "population": 3.6, }, { "state": "Utah", "population": 3.3, }, { "state": "Iowa", "population": 3.2, }, { "state": "Nevada", "population": 3.1, }, { "state": "Arkansas", "population": 3, }, { "state": "Mississippi", "population": 3, }, { "state": "Kansas", "population": 2.9, }, { "state": "New Mexico", "population": 2.1, }, { "state": "Nebraska", "population": 2, }, { "state": "Idaho", "population": 1.8, }, { "state": "West Virginia", "population": 1.8, }, { "state": "Hawaii", "population": 1.5, }, { "state": "New Hampshire", "population": 1.4, }, { "state": "Maine", "population": 1.4, }, { "state": "Rhode Island", "population": 1.1, }, { "state": "Montana", "population": 1.1, }, { "state": "Delaware", "population": 1, }, { "state": "South Dakota", "population": 0.9, }, { "state": "North Dakota", "population": 0.8, }, { "state": "Alaska", "population": 0.7, }, { "state": "District of Columbia", "population": 0.7, }, { "state": "Vermont", "population": 0.6, }, { "state": "Wyoming", "population": 0.6, }, { "state": "Puerto Rico", "population": 3.3, }, ], "title": "US population by state", "subtitle": "2020 census, millions of people", "sourceNote": "Source: US Census Bureau", } # Run the Actor and wait for it to finish run = client.actor("jumblemog/map-chart-generator").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "data": [ { "state": "California", "population": 39.5 }, { "state": "Texas", "population": 29.1 }, { "state": "Florida", "population": 21.5 }, { "state": "New York", "population": 20.2 }, { "state": "Pennsylvania", "population": 13 }, { "state": "Illinois", "population": 12.8 }, { "state": "Ohio", "population": 11.8 }, { "state": "Georgia", "population": 10.7 }, { "state": "North Carolina", "population": 10.4 }, { "state": "Michigan", "population": 10.1 }, { "state": "New Jersey", "population": 9.3 }, { "state": "Virginia", "population": 8.6 }, { "state": "Washington", "population": 7.7 }, { "state": "Arizona", "population": 7.2 }, { "state": "Massachusetts", "population": 7 }, { "state": "Tennessee", "population": 6.9 }, { "state": "Indiana", "population": 6.8 }, { "state": "Maryland", "population": 6.2 }, { "state": "Missouri", "population": 6.2 }, { "state": "Wisconsin", "population": 5.9 }, { "state": "Colorado", "population": 5.8 }, { "state": "Minnesota", "population": 5.7 }, { "state": "South Carolina", "population": 5.1 }, { "state": "Alabama", "population": 5 }, { "state": "Louisiana", "population": 4.7 }, { "state": "Kentucky", "population": 4.5 }, { "state": "Oregon", "population": 4.2 }, { "state": "Oklahoma", "population": 4 }, { "state": "Connecticut", "population": 3.6 }, { "state": "Utah", "population": 3.3 }, { "state": "Iowa", "population": 3.2 }, { "state": "Nevada", "population": 3.1 }, { "state": "Arkansas", "population": 3 }, { "state": "Mississippi", "population": 3 }, { "state": "Kansas", "population": 2.9 }, { "state": "New Mexico", "population": 2.1 }, { "state": "Nebraska", "population": 2 }, { "state": "Idaho", "population": 1.8 }, { "state": "West Virginia", "population": 1.8 }, { "state": "Hawaii", "population": 1.5 }, { "state": "New Hampshire", "population": 1.4 }, { "state": "Maine", "population": 1.4 }, { "state": "Rhode Island", "population": 1.1 }, { "state": "Montana", "population": 1.1 }, { "state": "Delaware", "population": 1 }, { "state": "South Dakota", "population": 0.9 }, { "state": "North Dakota", "population": 0.8 }, { "state": "Alaska", "population": 0.7 }, { "state": "District of Columbia", "population": 0.7 }, { "state": "Vermont", "population": 0.6 }, { "state": "Wyoming", "population": 0.6 }, { "state": "Puerto Rico", "population": 3.3 } ], "title": "US population by state", "subtitle": "2020 census, millions of people", "sourceNote": "Source: US Census Bureau" }' | apify call jumblemog/map-chart-generator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,jumblemog/map-chart-generator" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/IdtVSLasUa7Xae8r2/builds/O3Ex2LlGvylZuhHOu/openapi.json