API 사용 예

공개 데이터를 쿼리하고, 데이터베이스를 동기화하고, 오비트랩 판독값을 보내고, 방문을 차단하기 위한 컬, Python 및 JavaScript의 기성 레시피입니다.

/ko-kr/api참조로 돌아가기

첫 번째 단계

모든 호출은 동일한 데이터베이스에서 발생하며 JSON을 반환합니다. 공용 끝점에는 인증이 필요하지 않습니다. 비공개에는 액세스 키가 필요합니다.

기본 주소

/ko-kr/api

언어 접두어는 URL의 일부입니다. (ko-kr), 그러나 반환된 데이터는 변경되지 않습니다. 기록은 현장에 등록된 것과 정확히 동일하게 은행에서 제공됩니다.

빠른 테스트
curl -G -d "municipality=Ponta Pora" --data-urlencode "country=Brasil" \
  /ko-kr/api/lastcountingpublic

응답이 JSON 목록인 경우 통합이 이미 작동 중인 것입니다.

키는 URL에 들어갑니다. POST를 포함한 모든 개인 끝점에서 key 쿼리 문자열에서 읽혀집니다. (?key=SUA_CHAVE). 양식 본문으로만 보내면 반환됩니다. 404 "Wrong key". 다른 필드는 요청 본문에 계속 표시됩니다.

공개 데이터 참조

엔드포인트 /api/lastcountingpublic 역학 위도, 경도, 주 및 연도와 함께 최신 계란 수를 반환합니다. 지도, 패널, 연구의 출발점입니다.

GET/api/lastcountingpublic공공의
curl
curl -G \
  --data-urlencode "municipality=Ponta Pora" \
  --data-urlencode "date_start=2025-01-01" \
  --data-urlencode "date_end=2025-12-31" \
  /ko-kr/api/lastcountingpublic
Python
import requests

BASE = "/ko-kr/api"

resposta = requests.get(
    BASE + "/lastcountingpublic",
    params={
        "municipality": "Ponta Pora",
        "date_start": "2025-01-01",
        "date_end": "2025-12-31",
    },
    timeout=60,
)
resposta.raise_for_status()

for contagem in resposta.json():
    print(contagem["date"], contagem["ovitrap_id"], contagem["eggs"])
JavaScript
const BASE = "/ko-kr/api";

const params = new URLSearchParams({
    state: "MS",
    date_start: "2025-01-01",
});

const resposta = await fetch(BASE + "/lastcountingpublic?" + params);
const contagens = await resposta.json();

console.log(contagens.length, "contagens");

동일한 위치 매개변수 (country, state, municipality) 이는 오비트랩, 블록, EDL, EDL 유지 관리 및 전략적 지점과 같은 다른 공용 엔드포인트에 적용됩니다. 엔드포인트 경로만 변경하면 이미 데이터 세트가 변경됩니다.

위치 매개변수가 없으면 엔드포인트는 브라질 전체에 대한 데이터를 반환합니다. 지방자치단체나 주별로 필터링하면 응답이 훨씬 빨라집니다.

모든 페이지 찾아보기

페이지를 매긴 엔드포인트 지원 page 1부터 100까지. 그 위의 API는 텍스트로 응답합니다. "Maximum pagination is 100" 상태 200 — 즉, 본문이 더 이상 목록이 아닙니다. 반복하기 전에 항상 유형을 확인하십시오.

Python
import requests

BASE = "/ko-kr/api"


def baixar_tudo(endpoint, **filtros):
    """Percorre as paginas ate a API devolver uma pagina vazia."""
    registros = []

    for pagina in range(1, 101):
        resposta = requests.get(
            BASE + endpoint,
            params=dict(filtros, page=pagina),
            timeout=60,
        )
        resposta.raise_for_status()
        dados = resposta.json()

        # limite de paginacao atingido: a API devolve uma string, nao uma lista
        if not isinstance(dados, list):
            print("Aviso:", dados)
            break

        if not dados:
            break

        registros.extend(dados)

    return registros


ovitrampas = baixar_tudo("/getmunicipalityovitrapspublic", municipality="Ponta Pora")
print(len(ovitrampas), "ovitrampas")
100페이지까지 가셨나요? 101페이지를 시도하는 대신 필터 범위를 좁히세요. 카운티별로 검색하거나 다음을 사용하세요. date_start e date_end 기간을 더 작은 간격으로 나누는 것입니다.

증분 동기화

미러링된 베이스를 유지하려면 실행할 때마다 모든 것을 다시 다운로드하지 마십시오. 엔드포인트 /api/lastcountingpublic 수락됨 id, 해당 식별자의 개수만 반환하며, date (포함 날짜) e date_collect (data de coleta).

Python
import json
import os
import requests

BASE = "/ko-kr/api"
ESTADO = "ultimo_id.json"


def ultimo_id_lido():
    if os.path.exists(ESTADO):
        with open(ESTADO) as arquivo:
            return json.load(arquivo)["counting_id"]
    return 0


def sincronizar():
    ultimo = ultimo_id_lido()
    novas = []

    for pagina in range(1, 101):
        resposta = requests.get(
            BASE + "/lastcountingpublic",
            params={"municipality": "Ponta Pora", "id": ultimo, "page": pagina},
            timeout=60,
        )
        resposta.raise_for_status()
        dados = resposta.json()

        if not isinstance(dados, list) or not dados:
            break

        novas.extend(dados)

    if novas:
        maior = max(item["counting_id"] for item in novas)
        with open(ESTADO, "w") as arquivo:
            json.dump({"counting_id": maior}, arquivo)

    return novas


print(len(sincronizar()), "contagens novas")

항상 가장 큰 값을 유지하세요. counting_id 실행 날짜가 아닌 수신됨: 오늘 필드에 입력된 개수는 이전 주를 참조할 수 있으며 ID별 필터는 이러한 레코드가 빠져나가는 것을 허용하지 않습니다.

CSV로 내보내기

공개 카운트는 이미 좌표와 함께 제공되므로 추가 가입 없이 스프레드시트를 생성하거나 지도를 제공할 수 있습니다.

Python
import csv
import requests

BASE = "/ko-kr/api"

COLUNAS = [
    "counting_id",
    "municipality",
    "state_code",
    "ovitrap_id",
    "latitude",
    "longitude",
    "week",
    "year",
    "eggs",
    "date",
    "date_collect",
]

resposta = requests.get(
    BASE + "/lastcountingpublic",
    params={"state": "MS", "date_start": "2025-01-01"},
    timeout=60,
)
contagens = resposta.json()

with open("contagens.csv", "w", newline="", encoding="utf-8") as arquivo:
    escritor = csv.DictWriter(arquivo, fieldnames=COLUNAS, extrasaction="ignore")
    escritor.writeheader()
    escritor.writerows(contagens)

print("Arquivo contagens.csv gerado com", len(contagens), "linhas")

데이터 보내기

다음 예시에서는 프라이빗 API를 사용하며 키가 필요합니다. 키의 지리적 범위는 기록할 수 있는 내용을 정의합니다. 즉, 지방자치단체 키는 지방자치단체 자체에만 기록합니다.

POST/api/postcounting사적인

기존 난소 트랩의 판독값 보내기

이미 등록된 난낭 트랩의 알 개수를 보냅니다. 오비트랩은 다음과 같은 위치에 있습니다. ovitrap_group_id 키의 지방 자치 단체 내에서 역학 주간은 현장에서 계산됩니다. date.

curl
curl -X POST \
  -d "ovitrap_group_id=97" \
  -d "ovitrap_lat=-7.000000" \
  -d "ovitrap_lng=-8.000000" \
  -d "date=2025-01-20" \
  -d "counting_observation_id=1" \
  -d "counting_eggs=5" \
  "/ko-kr/api/postcounting?key=SUA_CHAVE"
Python
import requests

BASE = "/ko-kr/api"
CHAVE = "SUA_CHAVE"

resposta = requests.post(
    BASE + "/postcounting",
    params={"key": CHAVE},          # a chave vai na URL
    data={                          # os dados vao no corpo
        "ovitrap_group_id": 97,
        "ovitrap_lat": -7.000000,
        "ovitrap_lng": -8.000000,
        "date": "2025-01-20",
        "counting_observation_id": 1,
        "counting_eggs": 5,
    },
    timeout=60,
)

print(resposta.status_code, resposta.json())
# 200 "Contagem registrada"
주목: 전송된 좌표가 등록된 좌표와 다른 경우, 난낭 트랩은 새 위치로 업데이트됩니다. 항상 판독 시 에이전트의 좌표가 아닌 해당 지점의 실제 좌표를 전송합니다.
POST/api/postcounting사적인

판독값 옆에 새로운 오비트랩을 설치합니다.

만약 ovitrap_group_id 지방 자치 단체에 아직 존재하지 않는 경우 동일한 요청으로 난소 트랩이 생성됩니다. 또한 주소와 해당되는 경우 유형을 보내십시오. (ovitrap_type_id: 1 도시, 패턴; 2 rural).

Python
import requests

BASE = "/ko-kr/api"
CHAVE = "SUA_CHAVE"

resposta = requests.post(
    BASE + "/postcounting",
    params={"key": CHAVE},
    data={
        "ovitrap_group_id": 96,
        "ovitrap_address_district": "Centro",
        "ovitrap_address_street": "Rua das Flores",
        "ovitrap_address_number": "123",
        "ovitrap_address_complement": "",
        "ovitrap_address_sector": "Setor 04",
        "ovitrap_responsable": "Maria Souza",
        "ovitrap_block_id": "12",
        "ovitrap_type_id": 2,          # 1 = urbana (padrao), 2 = rural
        "ovitrap_lat": -7.000000,
        "ovitrap_lng": -8.000000,
        "date": "2025-01-20",
        "counting_date_collect": "2025-01-27",
        "counting_observation_id": 1,
        "counting_eggs": 5,
    },
    timeout=60,
)

print(resposta.status_code, resposta.json())
구체적인 답변:
  • 400 — 부족 ovitrap_lat, ovitrap_lng ou ovitrap_group_id.
  • 400 — ovitrap_type_id 1, 2와는 다릅니다.
  • 404 — 이 수란관, 연도 및 주에 대한 카운트가 이미 있습니다.
  • 500 — 전송된 날짜가 미래 또는 유효하지 않은 역학 주간에 속합니다.
POST/api/postaction사적인

블록 방문 등록

사용 block_id 이미 등록된 블록에서 방문을 시작합니다. 블록이 아직 존재하지 않으면 전송 block_group_id 블록데이터를 이용하여 주요 지자체 내에서 자동으로 생성됩니다.

Python — 기존 블록
import requests

BASE = "/ko-kr/api"
CHAVE = "SUA_CHAVE"

visita = {
    "block_id": 97,
    "date": "2025-01-20",

    "block_land_residence": 10,
    "action_land_residence_out": 2,
    "action_land_residence_breedings": 1,
    "action_land_residence_treated": 1,

    "action_deposit_a1_quantity": 4,
    "action_deposit_a1_eliminated": 2,
    "action_deposit_a1_treated": 1,
    "action_deposit_a1_larvicid": 10,

    "action_observation": "Foco encontrado em pneus nos fundos do imovel.",
}

resposta = requests.post(
    BASE + "/postaction", params={"key": CHAVE}, data=visita, timeout=60
)

if resposta.status_code == 409:
    print("Ja existe visita para esse quarteirao nessa semana")
else:
    print(resposta.status_code, resposta.json())
Python — 블록 생성
visita = {
    "block_group_id": 97,
    "date": "2025-01-20",
    "block_address_district": "Centro Historico",
    "block_address_sector": "Setor 04 - Norte",
    "block_coordinates": "[[-7.123, -34.845], [-7.124, -34.846]]",
    "block_lat": -7.123456,
    "block_lng": -34.845678,
    "block_responsable": "Joao da Silva",

    "block_land_residence": 10,
    "action_land_residence_out": 2,
    "action_land_residence_breedings": 1,
    "action_land_residence_treated": 1,

    "action_observation": "Area com alta densidade de recipientes descartaveis.",
}

resposta = requests.post(
    BASE + "/postaction", params={"key": CHAVE}, data=visita, timeout=60
)
print(resposta.status_code, resposta.json())

부동산 및 예금 분야의 전체 목록 (a1, a2, b, c, d1, d2, e) 에 있습니다 엔드포인트 참조. 전송되지 않은 숫자 필드는 0으로 가정하지만 숫자가 아닌 값은 400을 반환합니다.

기록 삭제

제거는 확정적이며 항상 주요 자치단체로 제한됩니다.

curl
# leitura de uma ovitrampa (identificada pela ovitrampa + data)
curl -X POST -d "ovitrap_group_id=97" -d "date=2025-01-20" \
  "/ko-kr/api/postdeletecounting?key=SUA_CHAVE"

# a ovitrampa inteira
curl -X POST -d "ovitrap_group_id=97" \
  "/ko-kr/api/postdeleteovitrap?key=SUA_CHAVE"

# visita de um quarteirao (quarteirao + data)
curl -X POST -d "block_group_id=97" -d "date=2025-01-20" \
  "/ko-kr/api/postdeleteaction?key=SUA_CHAVE"

# o quarteirao inteiro
curl -X POST -d "block_group_id=97" \
  "/ko-kr/api/postdeleteblock?key=SUA_CHAVE"
잘못된 값으로 게시된 카운트를 수정하려면 다음을 사용하여 판독값을 제거하십시오. /api/postdeletecounting 그리고 다시 보내주세요 /api/postcounting — 다시 보내면 중복 오류가 반환됩니다.

오류 처리

응답 본문은 항상 메시지가 포함된 JSON 문자열입니다. 모든 오류가 다시 시도할 가치가 있는 것은 아니기 때문에 각 사례를 처리할 가치가 있습니다.

상황암호해야 할 일
"Wrong key"404키가 본문이 아닌 쿼리 문자열에 있는지 확인하세요.
이중 계산404이번 주에는 이미 난관에 대한 독서가 있습니다. 다시 보내기 전에 제거하세요.
중복 방문409이번 주에는 이미 블록 방문이 있습니다.
범위 외403해당 블록은 Chave 자치단체에 속하지 않습니다. 반복하지 마십시오.
필수 입력란이 누락되었습니다.400제출 내용을 수정하세요. 반복하면 동일한 오류가 반환됩니다.
잘못된 주 또는 연도500날짜가 허용된 역학 주간을 벗어났습니다. 필드를 수정하세요 date.
Python
import time
import requests

NAO_REPETIR = {400, 403, 404, 409}


def enviar(url, chave, dados, tentativas=3):
    for tentativa in range(tentativas):
        try:
            resposta = requests.post(
                url, params={"key": chave}, data=dados, timeout=60
            )
        except requests.RequestException as erro:
            print("Falha de rede:", erro)
            time.sleep(5 * (tentativa + 1))
            continue

        if resposta.status_code in NAO_REPETIR:
            print("Erro definitivo:", resposta.status_code, resposta.json())
            return None

        if resposta.ok:
            return resposta.json()

        # 500 e demais erros de servidor: espera progressiva e tenta de novo
        time.sleep(5 * (tentativa + 1))

    return None

모범 사례

  • 가능할 때마다 지방자치단체나 주별로 필터링합니다. 필터링하지 않으면 쿼리가 국가 전체를 검색합니다.
  • 증분 동기화를 선호합니다. id 매일 전체 기지를 낮추십시오.
  • 요청을 순차적으로 보냅니다. API는 클라이언트당 수십 개의 동시 호출을 위해 설계되지 않았습니다.
  • 반복하기 전에 응답이 목록인지 확인하십시오. 페이징 제한 메시지는 상태 200으로 제공됩니다.
  • 저장 counting_id 그리고 block_id 수신 — 이를 통해 Conta Ovos 기록을 시스템의 기록과 일치시킬 수 있습니다.
  • 역학 주간을 결정 분야로 간주합니다. Conta Ovos는 주당 난소 트랩당 한 번의 판독과 주당 블록당 한 번의 방문만 허용합니다.
  • 페이지를 팔로우하세요 mudanças 통합을 업데이트하기 전에.