Biklo for developersTESTsandbox-api.biklo.comchange

Search cities

GET/v1/geo/cities

scope catalog.read

Cursor-paginated and always filtered — the table holds 727k rows, so an unfiltered request is refused. Search covers both the local script and the latin form: q=Sofia finds София.

Query parameters#

NameExample
countryROISO country code
county_id—Restrict to one county
qcraioName prefix, either script
limit50Max 100
cursor—next_cursor from the previous page

Response#

FieldTypeDescription
countintegerHow many cities in this page — not the total.
next_cursorstring|nullPass back as ?cursor= for the next page. null means this was the last one. Romania alone has thousands of cities, so always follow the cursor rather than assuming one page.
dataarrayThe cities matching your filters.
data[].idintegerWhat you send as city_id on an address or pickup point. Free-text city names are never accepted — the courier needs this id.
data[].namestringName in local script.
data[].latin_namestringLatin transliteration, for display.
data[].countyobjectThe county it sits in.
data[].county.idintegerCounty id.
data[].county.namestringCounty name.
data[].county.codestringCounty code.
data[].latitudenumberLatitude, for map display.
data[].longitudenumberLongitude, for map display.
data[].is_capitalbooleanWhether it is the country capital.

Example

{
    "count": 1,
    "next_cursor": null,
    "data": [
        {
            "id": 1,
            "name": "Craiova",
            "latin_name": "Craiova",
            "county": {
                "id": 1,
                "name": "Dolj",
                "code": "DJ"
            },
            "latitude": 44.33,
            "longitude": 23.82,
            "is_capital": false
        }
    ]
}

Failures use the shared error envelope — a machine-readable code and a request_id to quote to support. Error handling.

curl -X GET "https://sandbox-api.biklo.com/v1/geo/cities?country=RO" \
  -H "Authorization: Bearer bk_test_YOUR_KEY"
<?php

$ch = curl_init('https://sandbox-api.biklo.com/v1/geo/cities?country=RO');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer bk_test_YOUR_KEY',
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "bk_test_YOUR_KEY");

var request = new HttpRequestMessage(
    new HttpMethod("GET"),
    "https://sandbox-api.biklo.com/v1/geo/cities?country=RO");

var response = await client.SendAsync(request);
var json = await response.Content.ReadAsStringAsync();

import requests

response = requests.get(
    "https://sandbox-api.biklo.com/v1/geo/cities?country=RO",
    headers={"Authorization": "Bearer bk_test_YOUR_KEY"},
)

data = response.json()

const response = await fetch("https://sandbox-api.biklo.com/v1/geo/cities?country=RO", {
  method: "GET",
  headers: {
    Authorization: "Bearer bk_test_YOUR_KEY"
  }
});

const data = await response.json();

import java.net.http.*;
import java.net.URI;

var client = HttpClient.newHttpClient();

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox-api.biklo.com/v1/geo/cities?country=RO"))
    .header("Authorization", "Bearer bk_test_YOUR_KEY")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());