Main.java

/*
 * Клиент API прямого геокодинга Atlorium — координаты по адресу.
 *
 * Запуск (работает сразу, без регистрации — на демо-ключе).
 * Начиная с Java 11 файл запускается напрямую, без компиляции и без зависимостей:
 *
 *     java Main.java "Казань, улица Баумана, 13"
 *
 * Боевой ключ: получить на https://atlorium.com и положить в переменную окружения
 * ATLORIUM_API_KEY. Код при этом не меняется.
 */

import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class Main {

    /**
     * Публичный демо-ключ. С ним API отвечает МОКАМИ (не данными реестра) — чтобы
     * можно было встроить и протестировать интеграцию до оплаты. Ответы
     * детерминированы: один и тот же запрос всегда даёт один и тот же результат,
     * поэтому на них можно писать стабильные тесты.
     */
    static final String SANDBOX_KEY = "ak_sandbox_demo_mockdata_v1";

    static final String API_KEY = envOr("ATLORIUM_API_KEY", SANDBOX_KEY);
    static final String BASE_URL = envOr("ATLORIUM_BASE_URL", "https://atlorium.com");

    static final HttpClient CLIENT = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30))
            .build();

    static String envOr(String key, String fallback) {
        String value = System.getenv(key);
        return (value == null || value.isEmpty()) ? fallback : value;
    }

    /** Ошибка API: HTTP-код разложен в человекочитаемую причину. */
    static class AtloriumException extends RuntimeException {
        private static final Map<Integer, String> REASONS = new HashMap<Integer, String>();

        static {
            REASONS.put(400, "Некорректный запрос: адресная строка пуста, слишком коротка или слишком длинна");
            REASONS.put(401, "API-ключ отсутствует, просрочен или недействителен");
            REASONS.put(402, "Недостаточно кредитов на балансе — пополните на https://atlorium.com");
            REASONS.put(404, "Адрес не найден либо найденное грубее уровня улицы (такой ответ не тарифицируется)");
            REASONS.put(429, "Превышен лимит запросов — повторите позже");
            REASONS.put(503, "Геокодер временно недоступен (за сбой на своей стороне мы не списываем деньги)");
        }

        final int status;

        AtloriumException(int status, String body) {
            super("HTTP " + status + ": "
                    + REASONS.getOrDefault(status, "Неизвестная ошибка")
                    + ". Ответ сервера: " + body.substring(0, Math.min(200, body.length())));
            this.status = status;
        }
    }

    static String send(HttpRequest request) throws IOException, InterruptedException {
        HttpResponse<byte[]> response = CLIENT.send(request, HttpResponse.BodyHandlers.ofByteArray());
        String body = new String(response.body(), StandardCharsets.UTF_8);
        if (response.statusCode() != 200) {
            throw new AtloriumException(response.statusCode(), body);
        }
        return body;
    }

    static String get(String path, String query) throws IOException, InterruptedException {
        String url = BASE_URL + path + (query.isEmpty() ? "" : "?" + query);
        return send(HttpRequest.newBuilder(URI.create(url))
                .header("Authorization", "Bearer " + API_KEY)
                .header("Accept", "application/json")
                .timeout(Duration.ofSeconds(30))
                .GET()
                .build());
    }

    static String post(String path, String jsonBody) throws IOException, InterruptedException {
        return send(HttpRequest.newBuilder(URI.create(BASE_URL + path))
                .header("Authorization", "Bearer " + API_KEY)
                .header("Accept", "application/json")
                .header("Content-Type", "application/json")
                .timeout(Duration.ofSeconds(30))
                .POST(HttpRequest.BodyPublishers.ofString(jsonBody, StandardCharsets.UTF_8))
                .build());
    }

    static String encode(String value) {
        return URLEncoder.encode(value, StandardCharsets.UTF_8);
    }

    // ── Вызовы API ───────────────────────────────────────────────────────────

    /** Координаты по адресу, записанному одной строкой в свободной форме. */
    static String geocode(String text, int size, boolean exactOnly) throws IOException, InterruptedException {
        return get("/api/geocodeforward",
                "text=" + encode(text) + "&size=" + size + "&exactOnly=" + exactOnly);
    }

    /**
     * Координаты по адресу, разложенному на поля. Устойчивее свободной строки, когда
     * адрес уже хранится по полям: снимается неопределённость, где город, а где улица.
     * Тарифицируется по отдельной ставке.
     */
    static String geocodeStructured(String address, String locality, String region, String postalCode, int size)
            throws IOException, InterruptedException {
        StringBuilder query = new StringBuilder("size=").append(size);
        if (address != null) query.append("&address=").append(encode(address));
        if (locality != null) query.append("&locality=").append(encode(locality));
        if (region != null) query.append("&region=").append(encode(region));
        if (postalCode != null) query.append("&postalCode=").append(encode(postalCode));
        return get("/api/geocodeforward/structured", query.toString());
    }

    /**
     * Пакетная обработка: до 1000 адресов за один вызов. Порядок ответов совпадает с
     * порядком запроса, ненайденная строка получает пустой список вариантов и не
     * прерывает пакет.
     */
    static String geocodeBatch(List<String> queries, int sizePerQuery) throws IOException, InterruptedException {
        StringBuilder body = new StringBuilder("{\"queries\":[");
        for (int i = 0; i < queries.size(); i++) {
            if (i > 0) body.append(',');
            body.append('"').append(escapeJson(queries.get(i))).append('"');
        }
        body.append("],\"sizePerQuery\":").append(sizePerQuery).append('}');
        return post("/api/geocodeforward/batch", body.toString());
    }

    /**
     * Карточка объекта по идентификатору из предыдущего ответа геокодинга.
     * Идентификатор присвоен государственным реестром и не меняется, поэтому
     * повторное обращение по нему дешевле и надёжнее нового поиска.
     */
    static String getPlace(String placeId, boolean includeBoundary) throws IOException, InterruptedException {
        return get("/api/geocodeforward/place",
                "placeId=" + encode(placeId) + "&includeBoundary=" + includeBoundary);
    }

    /**
     * Что относится к почтовому индексу: населённый пункт и улицы.
     * Дома не возвращаются — их на индекс десятки тысяч.
     */
    static String getPostcode(String code, int size) throws IOException, InterruptedException {
        return get("/api/geocodeforward/postcode", "code=" + encode(code) + "&size=" + size);
    }

    static String escapeJson(String value) {
        return value.replace("\\", "\\\\").replace("\"", "\\\"");
    }

    // ── Разбор JSON ──────────────────────────────────────────────────────────
    // Пример намеренно оставлен без внешних зависимостей, чтобы запускаться одной
    // командой `java Main.java`. В рабочем проекте берите Jackson или Gson и
    // маппьте ответ в полноценные классы — разбор ниже существует только ради
    // отсутствия pom.xml.

    static String str(String json, String field) {
        Matcher matcher = Pattern.compile("\"" + field + "\"\\s*:\\s*\"((?:[^\"\\\\]|\\\\.)*)\"").matcher(json);
        return matcher.find() ? matcher.group(1).replace("\\\"", "\"") : null;
    }

    static Double number(String json, String field) {
        Matcher matcher = Pattern.compile("\"" + field + "\"\\s*:\\s*(-?\\d+(?:\\.\\d+)?)").matcher(json);
        return matcher.find() ? Double.valueOf(matcher.group(1)) : null;
    }

    static int intOf(String json, String field) {
        Double value = number(json, field);
        return value == null ? 0 : value.intValue();
    }

    /**
     * Возвращает содержимое вложенного объекта или массива по имени поля, считая
     * скобки. Регулярным выражением такое не берётся: во вложенном объекте свои
     * скобки, и «до первой закрывающей» обрезало бы его посередине.
     */
    static String block(String json, String field, char open, char close) {
        int key = json.indexOf("\"" + field + "\"");
        if (key < 0) return null;

        int start = json.indexOf(open, key);
        if (start < 0) return null;

        int depth = 0;
        boolean inString = false;
        boolean escaped = false;

        for (int i = start; i < json.length(); i++) {
            char symbol = json.charAt(i);

            if (escaped) {
                escaped = false;
                continue;
            }
            if (symbol == '\\') {
                escaped = true;
                continue;
            }
            if (symbol == '"') {
                inString = !inString;
                continue;
            }
            if (inString) continue;

            if (symbol == open) depth++;
            else if (symbol == close && --depth == 0) return json.substring(start + 1, i);
        }
        return null;
    }

    /** Разбивает содержимое массива на объекты верхнего уровня. */
    static List<String> objects(String arrayBody) {
        List<String> result = new ArrayList<String>();
        if (arrayBody == null) return result;

        int depth = 0;
        int start = -1;
        boolean inString = false;
        boolean escaped = false;

        for (int i = 0; i < arrayBody.length(); i++) {
            char symbol = arrayBody.charAt(i);

            if (escaped) {
                escaped = false;
                continue;
            }
            if (symbol == '\\') {
                escaped = true;
                continue;
            }
            if (symbol == '"') {
                inString = !inString;
                continue;
            }
            if (inString) continue;

            if (symbol == '{') {
                if (depth == 0) start = i;
                depth++;
            } else if (symbol == '}' && --depth == 0 && start >= 0) {
                result.add(arrayBody.substring(start, i + 1));
            }
        }
        return result;
    }

    // ── Применение данных: годна ли координата для привязки к зданию ─────────
    // Ответ геокодера сам по себе — просто точка. Практический вопрос другой: можно
    // ли ставить на этой точке метку конкретного дома. Отвечают на него два поля,
    // читаемые вместе: layer («что нашли») и precision («чья это координата»).

    static final String USE = "USE";       // координату можно использовать как есть
    static final String VERIFY = "VERIFY"; // координата есть, но её стоит показать человеку
    static final String REJECT = "REJECT"; // для привязки к зданию не годится

    /** Решение по одному варианту. */
    static class Verdict {
        final String decision;
        final List<String> reasons;

        Verdict(String decision, List<String> reasons) {
            this.decision = decision;
            this.reasons = reasons;
        }

        static Verdict of(String decision, String reason) {
            List<String> reasons = new ArrayList<String>();
            reasons.add(reason);
            return new Verdict(decision, reasons);
        }
    }

    /**
     * Номер дома отделяется от названия улицы справа налево, по последнему отдельно
     * стоящему числу — то же правило, по которому разбирает строку сам сервис.
     * Поэтому «улица 8 Марта, 5» разбирается верно: частью названия остаётся то,
     * что ему принадлежит.
     */
    static final Pattern HOUSE_TAIL = Pattern.compile(
            "(\\d+[а-яёa-z]?(?:\\s*к\\s*\\d+)?)\\s*$", Pattern.CASE_INSENSITIVE | Pattern.UNICODE_CASE);

    /** Достаёт номер дома из исходной строки запроса, если он там был. */
    static String requestedHouse(String text) {
        Matcher matcher = HOUSE_TAIL.matcher(text.trim());
        return matcher.find() ? matcher.group(1) : null;
    }

    static String normalizeHouse(String house) {
        return house == null ? "" : house.replaceAll("[\\s.\\-]", "").toLowerCase(Locale.ROOT);
    }

    /** Выносит вердикт: можно ли привязывать этот вариант к конкретному зданию. */
    static Verdict assessCoordinate(String query, String match) {
        String precision = str(match, "precision");
        String wanted = requestedHouse(query);
        String got = str(match, "houseNumber");
        boolean mismatch = wanted != null && got != null
                && !normalizeHouse(wanted).equals(normalizeHouse(got));

        if ("exact".equals(precision)) {
            // Точное попадание в дом. Остаётся сверить, тот ли это дом, который просили:
            // сервис мог вернуть «13», когда спрашивали «13к2» — см. ветку range ниже.
            if (mismatch) {
                return Verdict.of(VERIFY, "Запрошен дом " + wanted + ", найден дом " + got);
            }
            return Verdict.of(USE, got != null ? "Точная координата дома " + got : "Точная координата объекта");
        }

        if ("range".equals(precision)) {
            // range означает одно из двух: номер вычислен между соседними домами либо
            // совпадение было неполным. И то и другое — «найдено с оговоркой»: точка
            // рядом с нужным зданием, но не обязательно на нём.
            List<String> reasons = new ArrayList<String>();
            reasons.add("Номер вычислен между соседними домами либо совпадение неполное");
            if (mismatch) {
                reasons.add("запрошен дом " + wanted + ", найден дом " + got);
            }
            return new Verdict(VERIFY, reasons);
        }

        if ("street".equals(precision)) {
            return Verdict.of(REJECT, "Дома в данных нет — отдан центр улицы");
        }

        // locality и area до клиента обычно не доходят: такие результаты сервис считает
        // слишком грубыми и отвечает 404, не списывая денег. Ветка оставлена, чтобы
        // неизвестное значение не превратилось молча в «годится».
        return Verdict.of(REJECT,
                "Уровень точности «" + precision + "» слишком груб для привязки к зданию");
    }

    // ── Печать ───────────────────────────────────────────────────────────────

    /**
     * Координаты печатаются с явной локалью ROOT: на машине с русской локалью
     * дробный разделитель по умолчанию — запятая, и вывод разошёлся бы с примером
     * в README, а на карте такая строка не разобралась бы вовсе.
     */
    static String formatPoint(String matchJson) {
        String pointJson = block(matchJson, "point", '{', '}');
        Double latitude = number(pointJson, "latitude");
        Double longitude = number(pointJson, "longitude");
        return trimZeros(latitude) + ", " + trimZeros(longitude);
    }

    static String trimZeros(Double value) {
        if (value == null) return "null";
        String text = String.format(Locale.ROOT, "%.6f", value);
        text = text.replaceAll("0+$", "");
        return text.endsWith(".") ? text.substring(0, text.length() - 1) : text;
    }

    static String padRight(String text, int width) {
        StringBuilder result = new StringBuilder(text.length() > width ? text.substring(0, width) : text);
        while (result.length() < width) result.append(' ');
        return result.toString();
    }

    static void printMatch(int index, String query, String match) {
        System.out.println(index + ". " + str(match, "label"));
        System.out.println("   " + formatPoint(match)
                + " · layer=" + str(match, "layer")
                + " · precision=" + str(match, "precision"));
        System.out.println("   Индекс " + str(match, "postalCode") + " · placeId " + str(match, "placeId"));

        Verdict verdict = assessCoordinate(query, match);
        System.out.println("   [" + verdict.decision + "] " + String.join("; ", verdict.reasons));
    }

    public static void main(String[] args) throws Exception {
        if (API_KEY.equals(SANDBOX_KEY)) {
            System.out.println("Демо-ключ: ответы сгенерированы (моки), не данные реестра.\n");
        }

        String query = args.length > 0 ? args[0] : "Казань, улица Баумана, 13";

        String result;
        try {
            result = geocode(query, 5, false);
        } catch (AtloriumException error) {
            System.err.println("Ошибка: " + error.getMessage());
            System.exit(1);
            return;
        }

        List<String> matches = objects(block(result, "matches", '[', ']'));
        System.out.println("Запрос: " + query);
        System.out.println("Найдено вариантов: " + matches.size() + "\n");

        for (int i = 0; i < matches.size(); i++) {
            printMatch(i + 1, query, matches.get(i));
            System.out.println();
        }

        // Пакетный режим — то, ради чего сервис обычно и подключают: обогатить
        // координатами накопленную выгрузку. Показываем главное: строки, по которым
        // ничего не нашлось, не прерывают пакет и не тарифицируются.
        List<String> batchQueries = new ArrayList<String>();
        batchQueries.add(query);
        batchQueries.add("Москва, Тверская 1");
        batchQueries.add("улицы с таким названием не существует");

        String batch;
        try {
            batch = geocodeBatch(batchQueries, 1);
        } catch (AtloriumException error) {
            System.err.println("Пакетный режим недоступен: " + error.getMessage());
            return;
        }

        List<String> items = objects(block(batch, "items", '[', ']'));
        System.out.println("Пакетная выгрузка (" + intOf(batch, "requested") + " строки):");

        for (int i = 0; i < items.size(); i++) {
            String item = items.get(i);
            List<String> itemMatches = objects(block(item, "matches", '[', ']'));
            String found = itemMatches.isEmpty()
                    ? "не найдено"
                    : formatPoint(itemMatches.get(0)) + " (" + str(itemMatches.get(0), "precision") + ")";
            System.out.println("  " + (i + 1) + ". " + padRight(str(item, "query"), 42) + " → " + found);
        }

        System.out.println("  Отправлено " + intOf(batch, "requested")
                + ", найдено " + intOf(batch, "found")
                + ", списано единиц " + intOf(batch, "billedUnits")
                + " — ненайденные строки не тарифицируются.");

        // Показывать источник данных обязательно: этого требует лицензия исходных наборов.
        System.out.println("\n" + str(result, "attribution"));
    }
}