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).



Call Examples in Different Languages


curl -X POST 'https://easycms.fi/public_api/get_cities' \
-H 'Authorization1: TOKEN' \
-d 'username=USERNAME&password=PASSWORD&account=ACCOUNT_ID'


$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']),
  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'}
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"))
    .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'
}).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'}).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")
        .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")
        });
        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.