Skip to main content
Choose the perfect format for your project. Each format is optimized for specific use cases and comes with different credit costs and integration patterns.

Format Overview

JSON

+2 Credits
  • Web applications
  • APIs and microservices
  • JavaScript/Node.js projects
  • Mobile app backends

NDJSON

+2 Credits
  • Streaming and ETL pipelines
  • Line-by-line processing
  • Bulk loading (BigQuery, Elasticsearch)
  • Append-only data logs

CSV

+3 Credits
  • Spreadsheet analysis
  • Data science workflows
  • Excel/Google Sheets
  • BI tools and dashboards

Excel

+4 Credits
  • Multi-sheet .xlsx workbooks
  • Business and reporting
  • Offline analysis (Sheets, Calc)
  • No-code sort, filter, pivot

Markdown

+3 Credits
  • Documentation and READMEs
  • Wikis and knowledge bases
  • Pull-request summaries
  • Human-readable tables

XML

+2 Credits
  • Enterprise systems
  • SOAP APIs
  • Legacy system integration
  • Configuration files

YAML

+2 Credits
  • Configuration files
  • DevOps and CI/CD
  • Documentation
  • Human-readable data

MySQL

+4 Credits
  • MySQL / MariaDB imports
  • Full schema with indexes
  • Foreign key constraints
  • Production-ready DDL

PostgreSQL

+5 Credits
  • PostgreSQL-specific DDL
  • Type inference and indexes
  • Constraints and check rules
  • PostGIS compatible

SQLite

+5 Credits
  • Embedded and mobile apps
  • Single-file database
  • Lightweight deployments
  • Zero-config setup

SQL Server

+5 Credits
  • Microsoft SQL Server DDL
  • T-SQL compatible
  • Enterprise deployments
  • Azure SQL ready

MongoDB

+4 Credits
  • NoSQL document store
  • Flexible schema queries
  • mongorestore compatible
  • Aggregation pipeline ready

GeoJSON

+4 Credits
  • Mapping and GIS
  • Spatial queries
  • Map libraries (Mapbox, Leaflet)
  • Compatible with PostGIS
PostgreSQL, SQLite, and SQL Server produce dialect-specific DDL with type inference, indexes, and constraints. MySQL produces a full schema with foreign keys and indexes. All SQL formats are ready-to-import.

JSON Format (+2 Credits)

The most popular format for modern web development. Perfect for APIs, web applications, and mobile backends.
Clean, nested structure with logical grouping:
Sample Countries Export
{
  "countries": [
    {
      "name": "United States",
      "iso2": "US",
      "iso3": "USA", 
      "phonecode": "1",
      "currency": "USD",
      "currency_symbol": "$",
      "region": "Americas",
      "subregion": "Northern America",
      "latitude": 37.09024,
      "longitude": -95.712891,
      "emoji": "🇺🇸",
      "native": "United States"
    },
    {
      "name": "Canada", 
      "iso2": "CA",
      "iso3": "CAN",
      "phonecode": "1", 
      "currency": "CAD",
      "currency_symbol": "C$",
      "region": "Americas",
      "subregion": "Northern America", 
      "latitude": 56.130366,
      "longitude": -106.346771,
      "emoji": "🇨🇦",
      "native": "Canada"
    }
  ],
  "metadata": {
    "total_countries": 2,
    "export_date": "2024-01-15T10:30:00Z",
    "fields": ["name", "iso2", "iso3", "phonecode", "currency"],
    "version": "1.0"
  }
}
Multi-dataset structure:
Countries + States Export
{
  "countries": [
    {
      "name": "United States",
      "iso2": "US",
      "states_count": 50
    }
  ],
  "states": [
    {
      "name": "California", 
      "iso2": "CA",
      "country_code": "US",
      "latitude": 36.778261,
      "longitude": -119.417932
    }
  ],
  "metadata": {
    "countries_count": 1,
    "states_count": 50,
    "export_date": "2024-01-15T10:30:00Z"
  }
}

CSV Format (+3 Credits)

Perfect for spreadsheet analysis, data science workflows, and business intelligence tools.
Clean, standardized CSV with headers:
Countries Export
name,iso2,iso3,phonecode,currency,currency_symbol,region,subregion,latitude,longitude,capital,emoji
United States,US,USA,1,USD,$,Americas,Northern America,37.09024,-95.712891,Washington,🇺🇸
Canada,CA,CAN,1,CAD,C$,Americas,Northern America,56.130366,-106.346771,Ottawa,🇨🇦
United Kingdom,GB,GBR,44,GBP,£,Europe,Northern Europe,55.378051,-3.435973,London,🇬🇧
Multi-sheet structure for combined datasets:
countries.csv
name,iso2,currency,capital
United States,US,USD,Washington
Canada,CA,CAD,Ottawa
states.csv
name,iso2,country_code,latitude,longitude
California,CA,US,36.778261,-119.417932
Texas,TX,US,31.968599,-99.901813

XML Format (+2 Credits)

Ideal for enterprise systems, SOAP APIs, and legacy system integrations that require structured, schema-validated data.
Well-formed XML with proper namespaces:
Countries Export
<?xml version="1.0" encoding="UTF-8"?>
<csc:export xmlns:csc="https://countrystatecity.in/schemas/v1" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="https://countrystatecity.in/schemas/v1 csc-schema.xsd">
  
  <csc:metadata>
    <csc:export_date>2024-01-15T10:30:00Z</csc:export_date>
    <csc:version>1.0</csc:version>
    <csc:total_records>250</csc:total_records>
  </csc:metadata>
  
  <csc:countries>
    <csc:country>
      <csc:basic_info>
        <csc:name>United States</csc:name>
        <csc:native_name>United States</csc:native_name>
        <csc:iso2>US</csc:iso2>
        <csc:iso3>USA</csc:iso3>
        <csc:emoji>🇺🇸</csc:emoji>
      </csc:basic_info>
      
      <csc:contact_info>
        <csc:phonecode>1</csc:phonecode>
        <csc:capital>Washington</csc:capital>
      </csc:contact_info>
      
      <csc:economic_info>
        <csc:currency code="USD" symbol="$">US Dollar</csc:currency>
        <csc:currency_name>US Dollar</csc:currency_name>
      </csc:economic_info>
      
      <csc:geographic_info>
        <csc:region>Americas</csc:region>
        <csc:subregion>Northern America</csc:subregion>
        <csc:coordinates>
          <csc:latitude>37.09024</csc:latitude>
          <csc:longitude>-95.712891</csc:longitude>
        </csc:coordinates>
      </csc:geographic_info>
      
      <csc:cultural_info>
        <csc:nationality>American</csc:nationality>
        <csc:native_name>United States</csc:native_name>
      </csc:cultural_info>
      
      <csc:timezones>
        <csc:timezone>America/New_York</csc:timezone>
        <csc:timezone>America/Chicago</csc:timezone>
        <csc:timezone>America/Denver</csc:timezone>
        <csc:timezone>America/Los_Angeles</csc:timezone>
      </csc:timezones>
    </csc:country>
  </csc:countries>
</csc:export>

YAML Format (+2 Credits)

Human-readable format perfect for configuration files, documentation, and DevOps workflows.
Clean, hierarchical YAML structure:
Countries Export
metadata:
  export_date: "2024-01-15T10:30:00Z"
  version: "1.0"
  total_countries: 250
  fields:
    - name
    - iso2
    - currency
    - region

countries:
  - name: "United States"
    iso2: "US"
    iso3: "USA"
    basic_info:
      native_name: "United States"
      emoji: "🇺🇸"
      capital: "Washington"
    
    contact_info:
      phonecode: "1"
      tld: ".us"
    
    economic_info:
      currency: "USD"
      currency_symbol: "$"
      currency_name: "US Dollar"
    
    geographic_info:
      region: "Americas"
      subregion: "Northern America"
      coordinates:
        latitude: 37.09024
        longitude: -95.712891
    
    cultural_info:
      nationality: "American"
      native_name: "United States"
    
    timezones:
      - "America/New_York"
      - "America/Chicago"
      - "America/Denver"
      - "America/Los_Angeles"

  - name: "Canada"
    iso2: "CA" 
    iso3: "CAN"
    basic_info:
      native_name: "Canada"
      emoji: "🇨🇦"
      capital: "Ottawa"
    
    economic_info:
      currency: "CAD"
      currency_symbol: "C$"
      currency_name: "Canadian Dollar"
    
    geographic_info:
      region: "Americas"
      subregion: "Northern America"
      coordinates:
        latitude: 56.130366
        longitude: -106.346771

SQL Format (+4 Credits, dialects +5)

Ready-to-execute SQL statements for direct database imports, perfect for production deployments and data migrations.
Complete database schema with relationships:
Countries & States Export
-- CSC Export Generated SQL
-- Generated on: 2024-01-15T10:30:00Z
-- Version: 1.0
-- Contains: Countries, States

-- Drop existing tables (optional)
-- DROP TABLE IF EXISTS states;
-- DROP TABLE IF EXISTS countries;

-- Create countries table
CREATE TABLE IF NOT EXISTS countries (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    iso2 CHAR(2) UNIQUE NOT NULL,
    iso3 CHAR(3) UNIQUE NOT NULL,
    numeric_code VARCHAR(10),
    phonecode VARCHAR(20),
    capital VARCHAR(255),
    currency CHAR(3),
    currency_name VARCHAR(100),
    currency_symbol VARCHAR(10),
    tld VARCHAR(10),
    native VARCHAR(255),
    region VARCHAR(100),
    subregion VARCHAR(100),
    latitude DECIMAL(10, 8),
    longitude DECIMAL(11, 8),
    emoji VARCHAR(10),
    emojiU VARCHAR(50),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    flag BOOLEAN DEFAULT TRUE,
    
    -- Indexes for performance
    INDEX idx_countries_iso2 (iso2),
    INDEX idx_countries_iso3 (iso3),
    INDEX idx_countries_region (region),
    INDEX idx_countries_currency (currency)
);

-- Create states table
CREATE TABLE IF NOT EXISTS states (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    country_id INTEGER NOT NULL,
    country_code CHAR(2) NOT NULL,
    fips_code VARCHAR(10),
    iso2 VARCHAR(10),
    type VARCHAR(50),
    latitude DECIMAL(10, 8),
    longitude DECIMAL(11, 8),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    flag BOOLEAN DEFAULT TRUE,
    wikiDataId VARCHAR(50),
    
    -- Foreign key relationship
    FOREIGN KEY (country_id) REFERENCES countries(id) ON DELETE CASCADE,
    
    -- Indexes
    INDEX idx_states_country_id (country_id),
    INDEX idx_states_country_code (country_code),
    INDEX idx_states_name (name)
);

-- Insert countries data
INSERT INTO countries (
    name, iso2, iso3, numeric_code, phonecode, capital, currency, 
    currency_name, currency_symbol, tld, native, region, subregion, 
    latitude, longitude, emoji, emojiU
) VALUES
('United States', 'US', 'USA', '840', '1', 'Washington', 'USD', 'US dollar', '$', '.us', 'United States', 'Americas', 'Northern America', 37.09024000, -95.71289100, '🇺🇸', 'U+1F1FA U+1F1F8'),
('Canada', 'CA', 'CAN', '124', '1', 'Ottawa', 'CAD', 'Canadian dollar', '$', '.ca', 'Canada', 'Americas', 'Northern America', 56.13036600, -106.34677100, '🇨🇦', 'U+1F1E8 U+1F1E6'),
('United Kingdom', 'GB', 'GBR', '826', '44', 'London', 'GBP', 'British pound', '£', '.uk', 'United Kingdom', 'Europe', 'Northern Europe', 55.37805100, -3.43597300, '🇬🇧', 'U+1F1EC U+1F1E7');

-- Insert states data (with proper country_id references)
INSERT INTO states (
    name, country_id, country_code, fips_code, iso2, type, 
    latitude, longitude, wikiDataId
) VALUES
('Alabama', (SELECT id FROM countries WHERE iso2 = 'US'), 'US', '01', 'AL', 'state', 32.31823140, -86.90229800, 'Q173'),
('Alaska', (SELECT id FROM countries WHERE iso2 = 'US'), 'US', '02', 'AK', 'state', 66.16044020, -153.36914700, 'Q797'),
('Alberta', (SELECT id FROM countries WHERE iso2 = 'CA'), 'CA', NULL, 'AB', 'province', 53.93327060, -116.57664600, 'Q1951');

-- Create views for common queries
CREATE VIEW countries_with_stats AS
SELECT 
    c.*,
    COUNT(s.id) as states_count,
    AVG(s.latitude) as avg_state_latitude,
    AVG(s.longitude) as avg_state_longitude
FROM countries c
LEFT JOIN states s ON c.id = s.country_id
GROUP BY c.id;

-- Create stored procedures for common operations
DELIMITER //
CREATE PROCEDURE GetCountryWithStates(IN country_code CHAR(2))
BEGIN
    SELECT c.*, s.name as state_name, s.iso2 as state_iso2
    FROM countries c
    LEFT JOIN states s ON c.id = s.country_id
    WHERE c.iso2 = country_code
    ORDER BY s.name;
END //
DELIMITER ;

-- Grant permissions (adjust as needed)
-- GRANT SELECT, INSERT, UPDATE ON countries TO 'app_user'@'%';
-- GRANT SELECT, INSERT, UPDATE ON states TO 'app_user'@'%';

MongoDB Format (+4 Credits)

A mongodump-compatible BSON/JSON export ready to load directly into MongoDB using mongorestore or mongoimport.
Document structure for countries:
Sample Countries Export
[
  {
    "_id": { "$oid": "64f1a2b3c4d5e6f7a8b9c0d1" },
    "name": "India",
    "iso2": "IN",
    "iso3": "IND",
    "phonecode": "+91",
    "capital": "New Delhi",
    "currency": "INR",
    "currency_symbol": "₹",
    "region": "Asia",
    "subregion": "Southern Asia",
    "latitude": 20.593684,
    "longitude": 78.96288,
    "emoji": "🇮🇳"
  }
]
Nested states export:
Countries with States
[
  {
    "_id": { "$oid": "64f1a2b3c4d5e6f7a8b9c0d2" },
    "name": "India",
    "iso2": "IN",
    "states": [
      { "name": "Maharashtra", "state_code": "MH", "latitude": 19.7515, "longitude": 75.7139 },
      { "name": "Karnataka", "state_code": "KA", "latitude": 15.3173, "longitude": 75.7139 }
    ]
  }
]

GeoJSON Format (+4 Credits)

GeoJSON is a standard format for encoding geographical data structures. Each city or region is exported as a GeoJSON Feature with coordinates and properties, making it directly usable with mapping libraries and spatial databases.
FeatureCollection for cities:
Sample GeoJSON Export
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [-118.24368, 34.05223]
      },
      "properties": {
        "id": 111968,
        "name": "Los Angeles",
        "state_code": "CA",
        "state_name": "California",
        "country_code": "US",
        "country_name": "United States"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [72.87765, 19.07283]
      },
      "properties": {
        "id": 1,
        "name": "Mumbai",
        "state_code": "MH",
        "state_name": "Maharashtra",
        "country_code": "IN",
        "country_name": "India"
      }
    }
  ]
}
Coordinates follow the GeoJSON standard: [longitude, latitude] (not [latitude, longitude]). The coordinate reference system is WGS 84 (EPSG:4326).

Format Selection Guide

Choosing the right format can save you credits and development time. Use this decision tree:
1

Define Your Use Case

Ask yourself:
  • Where will this data be used?
  • Who will consume the data?
  • What tools do you have available?
  • Do you need real-time updates?
2

Consider Integration Complexity

Development Time vs Credit Cost:
Recommendation: JSON (+2 credits)
  • Native JavaScript support
  • Easy API integration
  • No additional parsing needed
  • Perfect for React, Vue, Angular
Recommendation: CSV (+3 credits)
  • Excel/Google Sheets ready
  • Pandas compatibility
  • Tableau/PowerBI import
  • Statistical analysis tools
Recommendation: XML (+2 credits)
  • Schema validation
  • SOAP web services
  • Legacy system integration
  • Structured data requirements
Recommendation: YAML (+2 credits)
  • Human-readable format
  • Kubernetes configs
  • CI/CD pipelines
  • Documentation-friendly
Recommendation: SQL (+4 credits) or PostgreSQL/SQL Server/SQLite3 (+5 credits)
  • Direct database import
  • Proper relationships
  • Production-ready
  • Migration-friendly
3

Calculate Total Cost

Final Cost Formula:
Total Credits = Dataset Cost + Format Cost

Examples:
- Countries (1) + JSON (1) = 2 credits
- Countries (1) + States (2) + CSV (1) = 4 credits
- Cities (3) + SQL (3) = 6 credits

Best Practices by Format

Performance Tips:
Lazy Loading
// Don't load all data at once for large datasets
class GeoDataLoader {
  async loadCountries() {
    if (!this.countriesCache) {
      const response = await fetch('/data/countries.json');
      this.countriesCache = await response.json();
    }
    return this.countriesCache;
  }
  
  async loadStatesByCountry(countryCode) {
    const cacheKey = `states_${countryCode}`;
    if (!this.statesCache[cacheKey]) {
      const response = await fetch(`/data/states/${countryCode}.json`);
      this.statesCache[cacheKey] = await response.json();
    }
    return this.statesCache[cacheKey];
  }
}
Memory Management:
Efficient Processing
// Process large JSON files in chunks
function processCountriesInBatches(countries, batchSize = 100) {
  const results = [];
  for (let i = 0; i < countries.length; i += batchSize) {
    const batch = countries.slice(i, i + batchSize);
    const processed = batch.map(processCountry);
    results.push(...processed);
    
    // Allow garbage collection between batches
    if (i % 1000 === 0) {
      await new Promise(resolve => setTimeout(resolve, 0));
    }
  }
  return results;
}

NDJSON Format (+2 Credits)

NDJSON (Newline-Delimited JSON) writes one JSON object per line with no enclosing array, so each line is an independent, fully-valid JSON record. This makes it ideal for streaming, append-only logs, and big-data tools that process input line by line without loading the whole file into memory.
{"id":101,"name":"India","iso2":"IN","iso3":"IND","capital":"New Delhi","currency":"INR"}
{"id":231,"name":"United States","iso2":"US","iso3":"USA","capital":"Washington","currency":"USD"}
{"id":232,"name":"United Kingdom","iso2":"GB","iso3":"GBR","capital":"London","currency":"GBP"}
Because each line stands alone, you can stream an NDJSON export straight into tools like jq, BigQuery, ClickHouse, Spark, or Elasticsearch’s bulk API with no array-unwrapping step.

When to use NDJSON

Streaming & ETL

Process records one line at a time in data pipelines without buffering the entire dataset in memory.

Bulk loading

Feed warehouses and search engines (BigQuery, ClickHouse, Elasticsearch) that natively accept newline-delimited JSON.

Markdown Format (+3 Credits)

The Markdown export renders your selected data as GitHub-flavoured Markdown tables — one table per dataset, with a header row and one row per record. It is meant for documentation, READMEs, wikis, and pull-request descriptions where the data needs to be readable at a glance without any extra tooling.
| id  | name           | iso2 | iso3 | capital    | currency |
| --- | -------------- | ---- | ---- | ---------- | -------- |
| 101 | India          | IN   | IND  | New Delhi  | INR      |
| 231 | United States  | US   | USA  | Washington | USD      |
| 232 | United Kingdom | GB   | GBR  | London     | GBP      |
Markdown is best for smaller, curated exports embedded in docs. For large datasets, prefer CSV or JSON — a table with tens of thousands of rows is impractical to render in a Markdown viewer.

When to use Markdown

Documentation

Drop ready-made tables into READMEs, wikis, or Mintlify / Docusaurus pages.

Reports & PRs

Share a quick, readable snapshot of geographical data in issues, pull requests, or notes.

Excel Format (+4 Credits)

The Excel export produces a native .xlsx workbook — a binary spreadsheet with one worksheet per dataset (Countries, States, Cities), a bold header row, and sensible column widths. It opens directly in Microsoft Excel, Google Sheets, LibreOffice Calc, or Numbers with no import step.
Use the native .xlsx export when you want a ready-to-share workbook with multiple sheets. If you only need a single table for scripting or BI ingestion, CSV is lighter and costs one credit less.

When to use Excel

Business & reporting

Hand a polished, multi-sheet workbook to analysts and stakeholders who live in spreadsheets.

Offline analysis

Sort, filter, pivot, and chart geographical data without writing any code.

Need help choosing a format? Consider your primary use case:
  • Quick prototyping: Start with JSON for web apps
  • Data analysis: Use CSV for spreadsheet compatibility
  • Production database: Invest in SQL for proper setup
  • Configuration management: YAML for readability
  • Streaming & big data: Use NDJSON for line-delimited records

View Pricing

See detailed pricing for all formats and credit packages