# GeoNames Places + Postal Codes Scraper (`parseforge/geonames-places-scraper`) Actor Pull populated places, admin divisions, and postal codes from GeoNames bulk dumps. Returns geonameId, name, lat/lng, population, elevation, timezone, alternate names, admin codes. Three modes: global cities (200K+ โ‰ฅ1000 pop), full per-country dump, or postal codes per country. No API key needed. - **URL**: https://apify.com/parseforge/geonames-places-scraper.md - **Developed by:** [ParseForge](https://apify.com/parseforge) (community) - **Categories:** Travel, Education, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $16.00 / 1,000 result items This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ![ParseForge Banner](https://github.com/ParseForge/apify-assets/blob/ad35ccc13ddd068b9d6cba33f323962e39aed5b2/banner.jpg?raw=true) ## ๐Ÿ“ GeoNames Places + Postal Codes Scraper > ๐Ÿš€ **Pull populated places, admin divisions, and postal codes from GeoNames: lat/lng, hierarchy, population, timezone, alternate names.** > ๐Ÿ•’ **Last updated:** 2026-05-07 ยท **๐Ÿ“Š 22 fields** per record ยท **12M+ places** ยท admin1/2/3 hierarchy ยท stable codes ยท postal codes ยท alternate names in 100+ languages The **GeoNames Places + Postal Codes Scraper** pulls reference geographic data from GeoNames, the most-cited open gazetteer worldwide. Output includes the geonameId, place name (in the requested language), country, full administrative hierarchy with stable codes, latitude/longitude, population, elevation, timezone, and feature classification. GeoNames covers **12+ million populated places** plus 4M+ alternate names, every official administrative division, and country postal codes. Three modes: search by name, list children of a country/admin division, or pull postal codes by country. Use cases include localized dropdowns, address autocomplete, geo-aware search, and OPAC integrations. | ๐ŸŽฏ Target Audience | ๐Ÿ’ก Primary Use Cases | |---|---| | Travel platforms, e-commerce checkout, address autocomplete, geo-search, GIS engineers, journalists | Country/state/city dropdowns, postal-code validation, geo-aware search, fact-card population, alt-name disambiguation | --- ### ๐Ÿ“‹ What the GeoNames Places + Postal Codes Scraper does Five filtering workflows in a single run: - ๐Ÿ” **Search by name.** Match populated places by name with optional country and feature-class filter. - ๐Ÿ—บ๏ธ **Admin hierarchy.** List every populated place under a country, with admin1/2/3 codes. - ๐Ÿ“ฎ **Postal codes.** Pull every postal code in a country with city + admin attribution. - ๐ŸŒ **Multilingual names.** Place names in 20+ languages with `lang` parameter. - ๐Ÿ“Š **Rich metadata.** Population, elevation, timezone, feature class for every record. > ๐Ÿ’ก **Why it matters:** clean, server-side filtering and fresh data on every run. --- ### ๐ŸŽฌ Full Demo _๐Ÿšง Coming soon: a 3-minute walkthrough showing how to go from sign-up to a downloaded dataset._ --- ### โš™๏ธ Input
InputTypeDefaultBehavior
maxItemsinteger10Records to return. Free plan caps at 10, paid plan up to 1,000,000.
modestring"cities"cities (global โ‰ฅ1000 pop), country (full per-country dump), postalcodes (per country).
countrystring""ISO-2 country code. Required for country and postalcodes modes.
querystring""Name substring filter (matches name + ASCII + alternate names).
featureClassstring""P=populated, A=admin, H=hydro, T=terrain, etc.
minPopulationinteger0Filter to places with at least this population.
**Example: search London worldwide.** ```json { "maxItems": 50, "mode": "cities", "query": "London" } ```` **Example: every postal code in Germany.** ```json { "maxItems": 2000, "mode": "postalcodes", "country": "DE" } ``` *** ### ๐Ÿ“Š Output Each record contains **22 fields**. Download as CSV, Excel, JSON, or XML. #### ๐Ÿงพ Schema | Field | Type | Example | |---|---|---| | ๐Ÿ†” `geonameId` | number | `2643743` | | ๐Ÿ“› `name` | string | `"London"` | | ๐Ÿ“› `toponymName` | string | `"London"` | | ๐Ÿ†” `countryCode` | string | `"GB"` | | ๐ŸŒ `countryName` | string | `"United Kingdom"` | | ๐Ÿ—บ๏ธ `adminCode1` | string | `"ENG"` | | ๐Ÿ—บ๏ธ `adminName1` | string | `"England"` | | ๐ŸŒ `lat` | number | `51.5074` | | ๐ŸŒ `lng` | number | `-0.1277` | | ๐Ÿ‘ฅ `population` | number | `8961989` | | ๐Ÿ“ `elevation` | number | null | `21` | | ๐Ÿ•’ `timezoneId` | string | `"Europe/London"` | | ๐Ÿท๏ธ `featureClass` | string | `"P"` | | ๐Ÿท๏ธ `featureCode` | string | `"PPLC"` | | ๐Ÿ”— `geonamesUrl` | string | `"https://www.geonames.org/2643743/"` | | ๐Ÿ“ฎ `postalCode` | string | null | `"SW1A"` | #### ๐Ÿ“ฆ Sample records
๐Ÿ‡ฌ๐Ÿ‡ง London ```json {"geonameId":2643743,"name":"London","countryCode":"GB","countryName":"United Kingdom","adminName1":"England","lat":51.5074,"lng":-0.1277,"population":8961989,"timezoneId":"Europe/London","featureCode":"PPLC"} ```
๐Ÿ“ฎ NYC postal ```json {"postalCode":"10001","placeName":"New York","countryCode":"US","adminName1":"New York","lat":40.7506,"lng":-73.9971} ```
*** ### โœจ Why choose this Actor | | Capability | |---|---| | ๐Ÿ“š | **12M+ places.** Most cited open gazetteer worldwide. | | ๐ŸŒ | **100+ languages.** Place names + alternate names in many languages. | | ๐Ÿ—บ๏ธ | **Stable hierarchy.** admin1/2/3 codes that join across data sources. | | ๐Ÿ“ฎ | **Postal codes built in.** Per-country postal-code lookup. | | โšก | **Fast.** 100 records in under 30 seconds. | *** ### ๐Ÿ“ˆ How it compares to alternatives | Approach | Cost | Coverage | Refresh | Filters | Setup | |---|---|---|---|---|---| | **โญ This Actor** | $5 free credit | **12M+** places | Live per run | mode, query, country, feature | โšก 2 min | | Manual geonames.org browse | Free | Manual | Live | Web filters | ๐Ÿ•’ Manual | | Mapbox / Google Geocoding | $$ | Similar but paid | Live | Yes | ๐Ÿข API key | | Raw GeoNames CSV dump | Free | All | Monthly | Bulk only | ๐Ÿข ETL pipeline | *** ### ๐Ÿš€ How to use 1. ๐Ÿ“ **Sign up.** [Create a free account with $5 credit](https://console.apify.com/sign-up?fpr=vmoqkp) (takes 2 minutes). 2. ๐ŸŒ **Open the Actor.** Find the GeoNames Places + Postal Codes Scraper on the Apify Store. 3. ๐ŸŽฏ **Set input.** Pick filters and `maxItems`. 4. ๐Ÿš€ **Run it.** Click **Start**. 5. ๐Ÿ“ฅ **Download.** Grab results in the **Dataset** tab as CSV, Excel, JSON, or XML. > โฑ๏ธ Total time from signup to dataset: **3-5 minutes.** No coding required. *** ### ๐Ÿ’ผ Business use cases
#### ๐Ÿ›’ E-commerce + SaaS - Country/state/city dropdown UIs - Postal-code validation on checkout - City autocomplete with population sort - Tax-region routing #### โœˆ๏ธ Travel + Logistics - Place autocomplete for trip planners - City pages for travel content - Distance-from-airport queries - Multi-language city names
#### ๐ŸŽ“ Education + Research - Geography quiz apps - Reproducible place datasets - Course materials - Geo-data primers #### ๐Ÿค– NLP + ML - Train geo-NER models - Build geo-aware embeddings - Power location-mention extraction - Reverse-geocode datasets
*** ### ๐Ÿ”Œ Automating GeoNames Places + Postal Codes Scraper Control the scraper programmatically: - ๐ŸŸข **Node.js.** Install the `apify-client` NPM package. - ๐Ÿ **Python.** Use the `apify-client` PyPI package. - ๐Ÿ“š See the [Apify API documentation](https://docs.apify.com/api/v2) for full details. The [Apify Schedules feature](https://docs.apify.com/platform/schedules) lets you trigger this Actor on any cron interval. *** ### ๐ŸŒŸ Beyond business use cases Data like this powers more than commercial workflows.
#### ๐ŸŽ“ Research and academia - Cross-language place studies - Reproducible gazetteer snapshots - Course exercises - Cultural-geography research #### ๐ŸŽจ Personal and creative - Personal travel maps - Hobby cartography - Newsletter content - Side projects with place data
#### ๐Ÿค Non-profit and civic - NGO geographic context - Open-data contributions - Civic-tech projects - Multilingual literacy resources #### ๐Ÿงช Experimentation - Train geo-NER models - Prototype location-aware agents - Build map-overlay experiments - Test geocoding pipelines
*** ### ๐Ÿค– Ask an AI assistant about this scraper Open a ready-to-send prompt in the AI of your choice: - ๐Ÿ’ฌ [**ChatGPT**](https://chat.openai.com/?q=How%20do%20I%20use%20the%20GeoNames%20Places%20%2B%20Postal%20Codes%20Scraper%20by%20ParseForge%20on%20Apify%3F%20Show%20me%20input%20examples%2C%20output%20fields%2C%20common%20use%20cases%2C%20and%20how%20to%20integrate%20it%20into%20a%20workflow.) - ๐Ÿง  [**Claude**](https://claude.ai/new?q=How%20do%20I%20use%20the%20GeoNames%20Places%20%2B%20Postal%20Codes%20Scraper%20by%20ParseForge%20on%20Apify%3F%20Show%20me%20input%20examples%2C%20output%20fields%2C%20common%20use%20cases%2C%20and%20how%20to%20integrate%20it%20into%20a%20workflow.) - ๐Ÿ” [**Perplexity**](https://perplexity.ai/search?q=How%20do%20I%20use%20the%20GeoNames%20Places%20%2B%20Postal%20Codes%20Scraper%20by%20ParseForge%20on%20Apify%3F%20Show%20me%20input%20examples%2C%20output%20fields%2C%20common%20use%20cases%2C%20and%20how%20to%20integrate%20it%20into%20a%20workflow.) - ๐Ÿ…’ [**Copilot**](https://copilot.microsoft.com/?q=How%20do%20I%20use%20the%20GeoNames%20Places%20%2B%20Postal%20Codes%20Scraper%20by%20ParseForge%20on%20Apify%3F%20Show%20me%20input%20examples%2C%20output%20fields%2C%20common%20use%20cases%2C%20and%20how%20to%20integrate%20it%20into%20a%20workflow.) *** ### โ“ Frequently Asked Questions #### ๐Ÿ”‘ Do I need a GeoNames account? No. The Actor downloads GeoNames bulk dumps directly (no username, no API key). Bulk dumps are GeoNames' canonical distribution and refresh daily. #### ๐Ÿงฉ How does it work? Pick a mode and supply the relevant filters. The Actor calls the GeoNames JSON API and emits one record per place, admin division, or postal code. #### ๐Ÿ“Š How many fields per record? Up to 22, including geonameId, name, country, admin hierarchy, lat/lng, population, elevation, timezone, feature class/code, and direct GeoNames URL. #### ๐ŸŒ Which languages are supported? 20+ via the `language` parameter, including English, Spanish, French, German, Italian, Portuguese, Japanese, Chinese, Russian, Arabic. #### ๐Ÿท๏ธ What are feature classes? GeoNames classifies places by type: P=populated places, A=admin divisions, H=hydrographic, T=terrain, S=spots/buildings, V=vegetation, R=roads, U=undersea, L=parks/areas. #### ๐Ÿ” Can I schedule runs? Yes. Use Apify Schedules for periodic refreshes. #### โš–๏ธ Is this data free? Yes. GeoNames publishes under Creative Commons Attribution that permits commercial reuse with attribution. #### ๐Ÿ’ณ Do I need a paid Apify plan? No. The free plan covers preview runs. #### ๐Ÿ†˜ What if a run fails? Apify retries transient errors. Most failures stem from invalid usernames or rate limits โ€” register your own free GeoNames account for reliable runs. #### ๐Ÿ“ฎ How do postal codes work? Each postal-code record includes the code, locality, country, admin1/2 codes/names, and lat/lng. Coverage varies by country. *** ### ๐Ÿ”Œ Integrate with any app GeoNames Places + Postal Codes Scraper connects to any cloud service via [Apify integrations](https://apify.com/integrations): - [**Make**](https://docs.apify.com/platform/integrations/make) - Automate multi-step workflows - [**Zapier**](https://docs.apify.com/platform/integrations/zapier) - Connect with 5,000+ apps - [**Slack**](https://docs.apify.com/platform/integrations/slack) - Get run notifications - [**Airbyte**](https://docs.apify.com/platform/integrations/airbyte) - Pipe data into your warehouse - [**GitHub**](https://docs.apify.com/platform/integrations/github) - Trigger runs from commits - [**Google Drive**](https://docs.apify.com/platform/integrations/drive) - Export datasets to Sheets *** ### ๐Ÿ”— Recommended Actors - [**๐ŸŒ REST Countries**](https://apify.com/parseforge/rest-countries-scraper) - Country reference data with capital, currency, flag - [**๐ŸŒ Public Holidays Worldwide**](https://apify.com/parseforge/public-holidays-scraper) - Public holidays for 100+ countries - [**๐ŸŒ Open-Meteo Weather**](https://apify.com/parseforge/open-meteo-weather-scraper) - Global weather forecasts - [**๐ŸŒ Wikidata Entity Search**](https://apify.com/parseforge/wikidata-entity-search-scraper) - 100M+ open knowledge-graph entities - [**๐Ÿ—บ๏ธ OpenStreetMap Nominatim**](https://apify.com/parseforge/nominatim-osm-scraper) - Geocode addresses worldwide via OSM > ๐Ÿ’ก **Pro Tip:** browse the complete [ParseForge collection](https://apify.com/parseforge) for more reference-data scrapers. *** **๐Ÿ†˜ Need Help?** [**Open our contact form**](https://tally.so/r/BzdKgA) to request a new scraper, propose a custom data project, or report an issue. *** > **โš ๏ธ Disclaimer:** this Actor is an independent tool and is not affiliated with, endorsed by, or sponsored by GeoNames or any contributing geographic-data provider. All trademarks mentioned are the property of their respective owners. Only publicly available open data is collected. # Actor input Schema ## `maxItems` (type: `integer`): Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000 ## `mode` (type: `string`): cities = global populated places โ‰ฅ1000 (~200K records). country = full per-country dump (all places). postalcodes = postal codes per country. ## `country` (type: `string`): Required for `country` and `postalcodes` modes. Optional filter for `cities` mode. ## `query` (type: `string`): Filter by name (case-insensitive substring; matches name + ASCII name + alternate names). ## `featureClass` (type: `string`): GeoNames feature class. P=populated places, A=admin divisions, H=hydrographic, T=mountain, S=spot, V=vegetation, R=road, U=undersea, L=parks/areas. ## `minPopulation` (type: `integer`): Filter to places with at least this population. Empty = no filter. ## Actor input object example ```json { "maxItems": 10, "mode": "cities", "country": "US", "featureClass": "" } ``` # Actor output Schema ## `overview` (type: `string`): No description # 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 = { "maxItems": 10, "mode": "cities", "country": "US", "query": "", "featureClass": "", "minPopulation": 0 }; // Run the Actor and wait for it to finish const run = await client.actor("parseforge/geonames-places-scraper").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 = { "maxItems": 10, "mode": "cities", "country": "US", "query": "", "featureClass": "", "minPopulation": 0, } # Run the Actor and wait for it to finish run = client.actor("parseforge/geonames-places-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "maxItems": 10, "mode": "cities", "country": "US", "query": "", "featureClass": "", "minPopulation": 0 }' | apify call parseforge/geonames-places-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=parseforge/geonames-places-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "GeoNames Places + Postal Codes Scraper", "description": "Pull populated places, admin divisions, and postal codes from GeoNames bulk dumps. Returns geonameId, name, lat/lng, population, elevation, timezone, alternate names, admin codes. Three modes: global cities (200K+ โ‰ฅ1000 pop), full per-country dump, or postal codes per country. No API key needed.", "version": "1.0", "x-build-id": "pbCKeSQzyvHcy1Cbg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/parseforge~geonames-places-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-parseforge-geonames-places-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/parseforge~geonames-places-scraper/runs": { "post": { "operationId": "runs-sync-parseforge-geonames-places-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/parseforge~geonames-places-scraper/run-sync": { "post": { "operationId": "run-sync-parseforge-geonames-places-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000" }, "mode": { "title": "Mode", "enum": [ "cities", "country", "postalcodes" ], "type": "string", "description": "cities = global populated places โ‰ฅ1000 (~200K records). country = full per-country dump (all places). postalcodes = postal codes per country.", "default": "cities" }, "country": { "title": "Country (ISO-2)", "enum": [ "", "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "KH", "CM", "CA", "CV", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CK", "CR", "HR", "CU", "CW", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "CI", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "XK", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "KP", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "RO", "RU", "RW", "RE", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "SD", "SR", "SJ", "SE", "CH", "SY", "ST", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "AE", "GB", "US", "UM", "VI", "UY", "UZ", "VU", "VA", "VE", "VN", "WF", "EH", "YE", "ZM", "ZW", "AX" ], "type": "string", "description": "Required for `country` and `postalcodes` modes. Optional filter for `cities` mode.", "default": "" }, "query": { "title": "Name search", "type": "string", "description": "Filter by name (case-insensitive substring; matches name + ASCII name + alternate names)." }, "featureClass": { "title": "Feature class filter", "enum": [ "", "A", "H", "L", "P", "R", "S", "T", "U", "V" ], "type": "string", "description": "GeoNames feature class. P=populated places, A=admin divisions, H=hydrographic, T=mountain, S=spot, V=vegetation, R=road, U=undersea, L=parks/areas.", "default": "" }, "minPopulation": { "title": "Minimum population", "minimum": 0, "type": "integer", "description": "Filter to places with at least this population. Empty = no filter." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```