# Batch API — GeoSearch

> The GeoSearch Batch API: 3 endpoints with parameters, quota costs, response bodies and code samples in six languages.

Base URL: https://geosearch.dev · Auth: X-API-Key header on every request.
HTML version: https://geosearch.dev/docs/api/batch

Batch lookup endpoints for multiple entities in a single request

## Batch lookup cities by IDs

`POST /v1/batch/cities` · Quota cost: 1 unit per requested id

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 |

### Code samples

#### curl

```bash
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

```go
// 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()
```

#### Python

```python
# 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
```

#### TypeScript

```typescript
// 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;
```

#### Ruby

```ruby
# 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
```

#### PHP

```php
// 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

```json
{
  "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 |

## Batch lookup countries by IDs

`POST /v1/batch/countries` · Quota cost: 1 unit per returned entity

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 |

### Code samples

#### curl

```bash
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

```go
// 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()
```

#### Python

```python
# 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
```

#### TypeScript

```typescript
// 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;
```

#### Ruby

```ruby
# 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
```

#### PHP

```php
// 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

```json
{
  "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 |

## Batch lookup regions by IDs

`POST /v1/batch/regions` · Quota cost: 1 unit per returned entity

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 |

### Code samples

#### curl

```bash
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

```go
// 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()
```

#### Python

```python
# 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
```

#### TypeScript

```typescript
// 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;
```

#### Ruby

```ruby
# 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
```

#### PHP

```php
// 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

```json
{
  "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 |