Batch API Reference

Batch lookup cities by IDs

POST/v1/batch/cities

Quota cost: 1 unit per requested id Try it

Returns multiple cities in a single request. Maximum 50 IDs per request.

Parameters

Name	Type	Required	Description
lang	string	optional	ISO 639-1 language code for localized names (e.g., de, fr, ja)
fields	string	optional	Comma-separated list of fields to include in the response

Request body

{
  "ids": [
    5391959,
    5128581,
    4887398
  ]
}

Code samples

curl Go Python TypeScript Ruby PHP

curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": [5391959, 5128581]}' \
  "https://geosearch.dev/v1/batch/cities"

// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
cities, _, err := client.BatchAPI.BatchCities(ctx).
    BatchRequest(geosearch.BatchRequest{Ids: []int64{5391959, 5128581}}).Execute()

# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    cities = geosearch.BatchApi(client).batch_cities(
        geosearch.BatchRequest(ids=[5391959, 5128581])).data

// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, BatchApi } from "@geosearch/client";

const api = new BatchApi(new Configuration({ apiKey: "YOUR_KEY" }));
const cities = (await api.batchCities({ batchRequest: { ids: [5391959, 5128581] } })).data;

# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
cities = GeoSearch::BatchApi.new.batch_cities(
  GeoSearch::BatchRequest.new(ids: [5391959, 5128581])).data

// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$request = new GeoSearch\Model\BatchRequest(["ids" => [5391959, 5128581]]);
$cities = (new GeoSearch\Api\BatchApi(null, $cfg))->batchCities($request)->getData();

Response

{
  "data": [
    {
      "id": 5391959,
      "geoname_id": 5391959,
      "name": "San Francisco",
      "ascii_name": "San Francisco",
      "country_code": "US",
      "admin1_code": "CA",
      "admin2_code": "075",
      "population": 873965,
      "elevation": 16,
      "timezone": "America/Los_Angeles",
      "latitude": 37.77493,
      "longitude": -122.41942,
      "country": {
        "iso_code": "US",
        "name": "United States"
      },
      "region": {
        "id": 5332921,
        "name": "California",
        "admin_code": "CA"
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6MjV9",
    "prev_cursor": "eyJpZCI6MX0",
    "has_next": true,
    "has_prev": false,
    "count": 25
  }
}

Errors

Status	Code	When
400	validation_error	Invalid request parameters
401	authentication_required	No API key was supplied
401	authentication_failed	The supplied API key is not valid
429	rate_limit_exceeded	Per-second throttle exceeded
429	quota_exceeded	Monthly quota exhausted

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "population_min",
        "issue": "must be a valid integer"
      }
    ],
    "request_id": "req_abc123"
  }
}

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}

Batch lookup countries by IDs

POST/v1/batch/countries

Quota cost: 1 unit per returned entity Try it

Returns multiple countries in a single request. Maximum 50 IDs per request.

Parameters

Name	Type	Required	Description
lang	string	optional	ISO 639-1 language code for localized names (e.g., de, fr, ja)
fields	string	optional	Comma-separated list of fields to include in the response

Request body

{
  "ids": [
    6252001,
    2635167,
    2921044
  ]
}

Code samples

curl Go Python TypeScript Ruby PHP

curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": [6252001, 2635167]}' \
  "https://geosearch.dev/v1/batch/countries"

// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
countries, _, err := client.BatchAPI.BatchCountries(ctx).
    BatchRequest(geosearch.BatchRequest{Ids: []int64{6252001, 2635167}}).Execute()

# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    countries = geosearch.BatchApi(client).batch_countries(
        geosearch.BatchRequest(ids=[6252001, 2635167])).data

// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, BatchApi } from "@geosearch/client";

const api = new BatchApi(new Configuration({ apiKey: "YOUR_KEY" }));
const countries = (await api.batchCountries({ batchRequest: { ids: [6252001, 2635167] } })).data;

# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
countries = GeoSearch::BatchApi.new.batch_countries(
  GeoSearch::BatchRequest.new(ids: [6252001, 2635167])).data

// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$request = new GeoSearch\Model\BatchRequest(["ids" => [6252001, 2635167]]);
$countries = (new GeoSearch\Api\BatchApi(null, $cfg))->batchCountries($request)->getData();

Response

{
  "data": [
    {
      "id": 1,
      "geoname_id": 6252001,
      "iso_code": "US",
      "iso3_code": "USA",
      "iso_numeric": 840,
      "fips_code": "US",
      "name": "United States",
      "capital": "Washington",
      "area_sq_km": 9833520,
      "population": 331002651,
      "continent_code": "NA",
      "tld": ".us",
      "currency_code": "USD",
      "currency_name": "Dollar",
      "phone": "1",
      "postal_code_format": "#####-####",
      "postal_code_regex": "^\\d{5}(-\\d{4})?$",
      "languages": [
        "en-US",
        "es-US"
      ],
      "neighbours": [
        "CA",
        "MX"
      ],
      "latitude": 39.76,
      "longitude": -98.5,
      "flag_emoji": "🇺🇸",
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                -124.7,
                48.4
              ],
              [
                -124.6,
                48.4
              ],
              [
                -124.6,
                48.3
              ],
              [
                -124.7,
                48.4
              ]
            ]
          ]
        ]
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6MjV9",
    "prev_cursor": "eyJpZCI6MX0",
    "has_next": true,
    "has_prev": false,
    "count": 25
  }
}

Errors

Status	Code	When
400	validation_error	Invalid request parameters
401	authentication_required	No API key was supplied
401	authentication_failed	The supplied API key is not valid
429	rate_limit_exceeded	Per-second throttle exceeded
429	quota_exceeded	Monthly quota exhausted

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "population_min",
        "issue": "must be a valid integer"
      }
    ],
    "request_id": "req_abc123"
  }
}

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}

Batch lookup regions by IDs

POST/v1/batch/regions

Quota cost: 1 unit per returned entity Try it

Returns multiple regions in a single request. Maximum 50 IDs per request.

Parameters

Name	Type	Required	Description
lang	string	optional	ISO 639-1 language code for localized names (e.g., de, fr, ja)
fields	string	optional	Comma-separated list of fields to include in the response

Request body

{
  "ids": [
    5332921,
    5128638,
    4862182
  ]
}

Code samples

curl Go Python TypeScript Ruby PHP

curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": [5332921, 5128638]}' \
  "https://geosearch.dev/v1/batch/regions"

// go get github.com/geosearch-dev/geosearch-go
client := geosearch.NewAPIClient(geosearch.NewConfiguration())
ctx := context.WithValue(context.Background(), geosearch.ContextAPIKeys,
    map[string]geosearch.APIKey{"apiKeyAuth": {Key: "YOUR_KEY"}})
regions, _, err := client.BatchAPI.BatchRegions(ctx).
    BatchRequest(geosearch.BatchRequest{Ids: []int64{5332921, 5128638}}).Execute()

# pip install git+https://github.com/geosearch-dev/geosearch-python.git
import geosearch

cfg = geosearch.Configuration(api_key={"apiKeyAuth": "YOUR_KEY"})
with geosearch.ApiClient(cfg) as client:
    regions = geosearch.BatchApi(client).batch_regions(
        geosearch.BatchRequest(ids=[5332921, 5128638])).data

// npm install github:geosearch-dev/geosearch-typescript
import { Configuration, BatchApi } from "@geosearch/client";

const api = new BatchApi(new Configuration({ apiKey: "YOUR_KEY" }));
const regions = (await api.batchRegions({ batchRequest: { ids: [5332921, 5128638] } })).data;

# gem 'geosearch', git: 'https://github.com/geosearch-dev/geosearch-ruby.git'
require "geosearch"

GeoSearch.configure { |c| c.api_key["X-API-Key"] = "YOUR_KEY" }
regions = GeoSearch::BatchApi.new.batch_regions(
  GeoSearch::BatchRequest.new(ids: [5332921, 5128638])).data

// composer config repositories.geosearch vcs https://github.com/geosearch-dev/geosearch-php.git
// composer require geosearch-dev/geosearch-php
$cfg = GeoSearch\Configuration::getDefaultConfiguration()
    ->setApiKey("X-API-Key", "YOUR_KEY");
$request = new GeoSearch\Model\BatchRequest(["ids" => [5332921, 5128638]]);
$regions = (new GeoSearch\Api\BatchApi(null, $cfg))->batchRegions($request)->getData();

Response

{
  "data": [
    {
      "id": 5332921,
      "geoname_id": 5332921,
      "country_code": "US",
      "admin_code": "CA",
      "name": "California",
      "ascii_name": "California",
      "level": 1,
      "parent_geoname_id": 6252001,
      "population": 39538223,
      "latitude": 36.778,
      "longitude": -119.418,
      "country": {
        "iso_code": "US",
        "name": "United States"
      },
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [
                -124.7,
                48.4
              ],
              [
                -124.6,
                48.4
              ],
              [
                -124.6,
                48.3
              ],
              [
                -124.7,
                48.4
              ]
            ]
          ]
        ]
      }
    }
  ],
  "meta": {
    "next_cursor": "eyJpZCI6MjV9",
    "prev_cursor": "eyJpZCI6MX0",
    "has_next": true,
    "has_prev": false,
    "count": 25
  }
}

Errors

Status	Code	When
400	validation_error	Invalid request parameters
401	authentication_required	No API key was supplied
401	authentication_failed	The supplied API key is not valid
429	rate_limit_exceeded	Per-second throttle exceeded
429	quota_exceeded	Monthly quota exhausted

400 validation_error

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "population_min",
        "issue": "must be a valid integer"
      }
    ],
    "request_id": "req_abc123"
  }
}

401 authentication_required

{
  "error": {
    "code": "authentication_required",
    "message": "API key required. Get one at /signup",
    "request_id": "req_abc123"
  }
}

401 authentication_failed

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key",
    "request_id": "req_abc123"
  }
}

429 rate_limit_exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later.",
    "request_id": "req_abc123"
  }
}

429 quota_exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted. You've used 2,000,000 of 2,000,000 requests for the current period, which resets on March 1, 2026. Upgrade for a higher limit.",
    "request_id": "req_abc123",
    "quota": {
      "limit": 2000000,
      "used": 2000000,
      "resets_at": "2026-03-01T00:00:00Z",
      "upgrade_url": "https://geosearch.dev/dashboard/billing"
    }
  }
}