Reference Data | Cities | Get Cities

Getting Cities Data

This document outlines the procedure for making API calls to retrieve city data from https://easycms.fi/public_api/get_cities/. Utilize various parameters to filter and customize your data retrieval.

City Data Retrieval

Fetch city data effectively using the below API call. Apply the IN or NOT_IN parameters as an array or a single integer to filter results according to your specific needs.

Endpoint and Method

  • Endpoint: https://easycms.fi/public_api/get_cities/
  • Method: POST

Parameters | Payload

Each parameter can be used individually or in combination to refine your data retrieval:

  • TOKEN (api_key): Your unique API key for authentication. How to Create API Credentials.

  • username: Your login username.

  • password: Your login password.

  • account: Your specific account ID.

  • Pagination: To manage data effectively, this endpoint supports fetching up to 50 products at a time.

  • Parameters:

    • start - Specify the starting point of the row from which to begin fetching products.
    • limit - Control the number of products returned in a single request. The maximum limit is 50, but you can opt for a smaller number based on your needs.

  • Filters: To manage data effectively, this endpoint supports fetching up to 50 products at a time.

  • IN - For filtering by city IDs (optional, array or single integer).

  • NOT_IN - For excluding specific city IDs (optional, array or single integer).

  • search - Search keyword (optional, string). Performs a partial (LIKE) match across multiple city columns. Supports multi-word queries separated by spaces or + — each word must match at least one column (AND logic between words). Case-insensitive.

    • Searchable columns: city_name, city_id, city_number, country_id



Understanding City Search

The search parameter enables broad keyword matching across all relevant columns of the city record. This is useful for:

  • Quick lookup: Find a city by partial name (searches across all language variants stored in city_name).
  • ID search: Find a city by its ID (city_id) or number (city_number).
  • Country filter: Find all cities belonging to a specific country by searching country_id.
  • Multi-word search: Use spaces to narrow results — e.g., search=Helsinki+40 will only return cities where one word matches "Helsinki" AND another matches "40" across any searchable columns.

Each word in the search query is matched independently across all searchable columns using OR within a word, and AND between words.



Call Examples in Different Languages


# Get all cities (default: first 50)
curl -X POST 'https://easycms.fi/public_api/get_cities' \
-H 'Authorization1: TOKEN' \
-d 'username=USERNAME&password=PASSWORD&account=ACCOUNT_ID'

# Search cities by keyword (matches city_name, city_id, city_number, country_id)
curl -X POST 'https://easycms.fi/public_api/get_cities' \
-H 'Authorization1: TOKEN' \
-d 'username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&search=Helsinki'

# Search cities by multiple keywords (AND logic)
curl -X POST 'https://easycms.fi/public_api/get_cities' \
-H 'Authorization1: TOKEN' \
-d 'username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&search=Helsinki+40'


$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://easycms.fi/public_api/get_cities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => http_build_query(['username' => 'USERNAME', 'password' => 'PASSWORD', 'account' => 'ACCOUNT_ID', 'search' => 'Helsinki']),
  CURLOPT_HTTPHEADER => array("Authorization1: TOKEN"),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;


import requests
url = "https://easycms.fi/public_api/get_cities"
headers = {"Authorization1": "TOKEN"}
payload = {'username': 'USERNAME', 'password': 'PASSWORD', 'account': 'ACCOUNT_ID', 'search': 'Helsinki'}
response = requests.post(url, headers=headers, data=payload)
print(response.text)


HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://easycms.fi/public_api/get_cities"))
    .headers("Authorization1", "TOKEN")
    .POST(HttpRequest.BodyPublishers.ofString("username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&search=Helsinki"))
    .build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());


const https = require('https');
const data = new URLSearchParams({ 
  username: 'USERNAME', 
  password: 'PASSWORD', 
  account: 'ACCOUNT_ID',
  search: 'Helsinki'
}).toString();
const options = {
  hostname: 'prolasku.fi',
  path: '/public_api/get_cities',
  method: 'POST',
  headers: {
    'Authorization1': 'TOKEN',
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': data.length
  }
};
const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => { console.log(data); });
});
req.on('error', (e) => { console.error(e); });
req.write(data);
req.end();


import React, { useEffect, useState } from 'react';
function App() {
  const [categoryData, setCategoryData] = useState('');
  useEffect(() => {
    const fetchData = async () => {
      try {
        const response = await fetch('https://easycms.fi/public_api/get_cities', {
          method: 'POST',
          headers: {'Authorization1': 'TOKEN', 'Content-Type': 'application/x-www-form-urlencoded'},
          body: new URLSearchParams({username: 'USERNAME', password: 'PASSWORD', account: 'ACCOUNT_ID', search: 'Helsinki'}).toString()
        });
        const data = await response.text();
        setCategoryData(data);
      } catch (error) {
        console.error(error);
      }
    };
    fetchData();
  }, []);
  return (
{categoryData}
);
}
export default App;


// Kotlin example requires using a third-party library like OkHttp for POST requests with a body
// Kotlin Example using OkHttp for POST request
import okhttp3.OkHttpClient
import okhttp3.FormBody
import okhttp3.Request

fun main() {
    val client = OkHttpClient()

    val formBody = FormBody.Builder()
        .add("username", "USERNAME")
        .add("password", "PASSWORD")
        .add("account", "ACCOUNT_ID")
        .add("search", "Helsinki")
        .build()

    val request = Request.Builder()
        .url("https://easycms.fi/public_api/get_cities")
        .post(formBody)
        .addHeader("Authorization1", "TOKEN")
        .build()

    client.newCall(request).execute().use { response ->
        if (!response.isSuccessful) throw IOException("Unexpected code $response")

        println(response.body?.string())
    }
}


using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
    static async Task Main()
    {
        var token = "TOKEN";
        var content = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair("username", "USERNAME"),
            new KeyValuePair("password", "PASSWORD"),
            new KeyValuePair("account", "ACCOUNT_ID"),
            new KeyValuePair("search", "Helsinki")
        });
        using (var httpClient = new HttpClient())
        {
            httpClient.DefaultRequestHeaders.Add("Authorization1", token);
            var response = await httpClient.PostAsync("https://easycms.fi/public_api/get_cities", content);
            if (response.IsSuccessStatusCode)
            {
                var responseData = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseData);
            }
            else
            {
                Console.WriteLine($"Error: {response.StatusCode}");
            }
        }
    }
}



Handling Endpoint Results

When you make a request to the endpoint, you receive a JSON response containing various keys and values. Here's an explanation of the response keys and their meanings:


# API Response Output Object Breakdown

This document provides a detailed breakdown of the response output object received from the API server. Each field in the JSON response is explained for better understanding and integration purposes.

## Fields Overview

The response object contains several fields providing information about a specific city, along with related geographical and localisation details. Below are the individual field descriptions:

### `city_id`
- **Type:** String
- **Description:** Unique identifier for the city.
- **Example:** `"1"`

### `city_number`
- **Type:** String
- **Description:** A numerical representation or code for the city.
- **Example:** `"19"`

### `country_id`
- **Type:** String
- **Description:** Unique identifier for the country to which the city belongs.
- **Example:** `"40"`

### `locale_code`
- **Type:** Boolean
- **Description:** Indicator of whether a locale code is available. Returns `false` if not available.
- **Example:** `false`

### `continent_code`
- **Type:** Boolean
- **Description:** Indicator of whether a continent code is available. Returns `false` if not available.
- **Example:** `false`

### `continent_name`
- **Type:** Boolean
- **Description:** Indicator of whether the name of the continent is available. Returns `false` if not available.
- **Example:** `false`

### `subdivision_1_iso_code`
- **Type:** Boolean
- **Description:** Indicator of whether the first subdivision ISO code is available. Returns `false` if not available.
- **Example:** `false`

### `subdivision_1_name`
- **Type:** Boolean
- **Description:** Indicator of whether the name of the first subdivision is available. Returns `false` if not available.
- **Example:** `false`

### `subdivision_2_iso_code`
- **Type:** Boolean
- **Description:** Indicator of whether the second subdivision ISO code is available. Returns `false` if not available.
- **Example:** `false`

### `subdivision_2_name`
- **Type:** Boolean
- **Description:** Indicator of whether the name of the second subdivision is available. Returns `false` if not available.
- **Example:** `false`

### `city_name`
- **Type:** Object
- **Description:** Contains the name of the city in various languages.
- **Sub-fields:** 
  - `en_gb`, `zh`, `fa_ir`, `sv`, `fi`, `ru`, `no`, `th`, `es`, `vi`
  - Each sub-field is a language code representing the city name in that language.
  - **Example:** `{"en_gb": "Helsinki", "zh": "赫尔辛基", ...}`

### `metro_code`
- **Type:** Boolean
- **Description:** Indicator of whether a metro code is available. Returns `false` if not available.
- **Example:** `false`

### `time_zone`
- **Type:** Boolean
- **Description:** Indicator of whether the time zone information is available. Returns `false` if not available.
- **Example:** `false`

### `visible`
- **Type:** String
- **Description:** Indicates if the city is visible in the system. "1" for visible, "0" for not visible.
- **Example:** `"1"`

### `parent_id`
- **Type:** Integer
- **Description:** Identifier for the parent entity of the city, if applicable. Zero often indicates no parent entity.
- **Example:** `0`

To see available languages please check endpoint /get_languages.

These key-value pairs provide comprehensive information about the cities and can be used for various purposes in your application.
    


{
    "INFO": {
        "start": 0,
        "limit": 50,
        "count": 48,
        "total_count": "48",
        "tip": "You may pass the table's main column identifier ex: city_id for tbl_cities, pid for tbl_products, cid for tbl_categories etc... to make a request for a single specific id from your query. EXAMPLE PARAM: city_id = 2 when sending the request for \"get_cities\" "
    },
    "OUTPUT": [
        {
            "city_id": "1",
            "city_number": "19",
            "country_id": "40",
            "locale_code": false,
            "continent_code": false,
            "continent_name": false,
            "subdivision_1_iso_code": false,
            "subdivision_1_name": false,
            "subdivision_2_iso_code": false,
            "subdivision_2_name": false,
            "city_name": {
                "en_gb": "Helsinki",
                "zh": "赫尔辛基",
                "fa_ir": "هلسینکی",
                "sv": "Helsingfors",
                "fi": "Helsinki",
                "ru": "Хельсинки",
                "no": "Helsinki",
                "th": "เฮลซิงกิ",
                "es": "Helsinki",
                "vi": "Helsinki"
            },
            "metro_code": false,
            "time_zone": false,
            "visible": "1",
            "parent_id": 0
        },
        {
            "city_id": "2",
            "city_number": "24",
            "country_id": "6",
            "locale_code": false,
            "continent_code": false,
            "continent_name": false,
            "subdivision_1_iso_code": false,
            "subdivision_1_name": false,
            "subdivision_2_iso_code": false,
            "subdivision_2_name": false,
            "city_name": {
                "en_gb": "Teheran",
                "zh": "德黑兰",
                "fa_ir": "تهران",
                "sv": "Teheran",
                "fi": "Teheran",
                "ru": "Тегеран",
                "no": "Teheran",
                "th": "Teheran",
                "es": "Teheran",
                "vi": "Teheran"
            },
            "metro_code": false,
            "time_zone": false,
            "visible": "1",
            "parent_id": 0
        },
        {
            "city_id": "3",
            "city_number": "22",
            "country_id": "40",
            "locale_code": false,
            "continent_code": false,
            "continent_name": false,
            "subdivision_1_iso_code": false,
            "subdivision_1_name": false,
            "subdivision_2_iso_code": false,
            "subdivision_2_name": false,
            "city_name": {
                "en_gb": "Turku",
                "zh": "图尔库",
                "fa_ir": "تورکو",
                "sv": "Åbo",
                "fi": "Turku",
                "ru": "Туркуа",
                "no": "Turku",
                "th": "Finland_ regions. kgm",
                "es": "Turku",
                "vi": "Turku"
            },
            "metro_code": false,
            "time_zone": false,
            "visible": "1",
            "parent_id": 0
        },
        {
            "city_id": "4",
            "city_number": "21",
            "country_id": "40",
            "locale_code": false,
            "continent_code": false,
            "continent_name": false,
            "subdivision_1_iso_code": false,
            "subdivision_1_name": false,
            "subdivision_2_iso_code": false,
            "subdivision_2_name": false,
            "city_name": {
                "en_gb": "Tampere",
                "zh": "坦佩雷",
                "fa_ir": "تامپره",
                "sv": "Tammerfors",
                "fi": "Tampere",
                "ru": "Тампере",
                "no": "Tampere",
                "th": "Finland_ regions. kgm",
                "es": "Tampere",
                "vi": "Tampere"
            },
            "metro_code": false,
            "time_zone": false,
            "visible": "1",
            "parent_id": 0
        },
        "response_type": "success",
        "message": "Data returned successfully"
    }
}

Error Handling

Here are the possible error messages and their meanings:

  • UN-AUTHORIZED - _user_name_password_is_set_but_wrong_value!: Incorrect username or password.
  • this_account_does_not_exist_or_your_credentials_do_not_match_this_account: The account doesn't exist or mismatched credentials.
  • UN-AUTHORIZED - header is set but the header value is not correct!: Incorrect authorization header value.
  • Maximum query size is 50 rows per query: Exceeded maximum limit of 50 rows per query.