Buscar Produtividade por Cidade

Descrição: Busca dados de produtividade agrícola filtrados por código da cidade e cultura.

Endpoint

GET/api/v1/integration/productivity/city

Regras

Atributos	Descrição	Tipo	Obrigatório	Validações
cityCode	Código IBGE da cidade	String	Sim	Ausente ou vazio retorna message.cityCode.required
culture	Tipo de cultura agrícola	String	Sim	Ausente ou vazio retorna message.culture.required. O valor é comparado sem distinção entre maiúsculas e minúsculas com a lista de culturas abaixo; valor não reconhecido retorna message.culture.not-found

Exemplo de Requisição

cURL

curl -X GET \
  -H "Authorization: {SUA_API_KEY}" \
  "https://api.merx.tech/api/v1/integration/productivity/city?cityCode=5208707&culture=SOY"

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.merx.tech/api/v1/integration/productivity/city?cityCode=5208707&culture=SOY"))
    .header("Authorization", "{SUA_API_KEY}")
    .GET()
    .build();

HttpClient client = HttpClient.newHttpClient();
try {
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
} catch (Exception e) {
    e.printStackTrace();
}

JavaScript

const params = new URLSearchParams({ cityCode: '5208707', culture: 'SOY' });
const response = await fetch(
  `https://api.merx.tech/api/v1/integration/productivity/city?${params}`,
  {
    method: 'GET',
    headers: {
      'Authorization': '{SUA_API_KEY}',
    },
  }
);
const data = await response.json();
console.log(data);

Python

import requests

url = "https://api.merx.tech/api/v1/integration/productivity/city"

headers = {
    "Authorization": "{SUA_API_KEY}",
}

params = {
    "cityCode": "5208707",
    "culture": "SOY"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

SDK Java

import com.merx.sdk.api.MerxClient;
import com.merx.sdk.core.Environment;

MerxClient merx = MerxClient.builder()
    .apiKey("{SUA_API_KEY}")
    .environment(Environment.SANDBOX)
    .build();

var productivity = merx.productivity().findByCity("4108304", "SOY");

Parâmetros

Parâmetros de Query:

Nome	Descrição	Tipo	Obrigatório
cityCode	Código IBGE da cidade	String	Sim
culture	Tipo de cultura agrícola. Valores: SOY, CORN, SUGAR_CANE, RICE, COTTON, COFFEE, CITRUS, PALM	String	Sim

Parâmetros de Cabeçalho

Nome	Descrição	Tipo	Obrigatório
Authorization	Chave de API obtida via support-api@merx.tech	String	Sim

Culturas Disponíveis

Valor	Descrição
SOY	Soja
CORN	Milho
SUGAR_CANE	Cana-de-açúcar
RICE	Arroz
COTTON	Algodão
COFFEE	Café
CITRUS	Citrus
PALM	Palma

Neste endpoint o culture é recebido como String livre e comparado com a lista acima sem distinção entre maiúsculas e minúsculas — SOY e soy são equivalentes. Por isso o erro de valor inválido difere dos demais endpoints de produtividade, onde o parâmetro é um enum e a falha ocorre já na conversão do parâmetro.

Respostas

• 200 - Ok

[
    {
        "city_code": 5208707,
        "culture": "SOY",
        "year": 2023,
        "productivity": 55.5,
        "removed": false,
        "created_at": 1673778600.000000000,
        "updated_at": 1673778600.000000000
    }
]

Campos da Resposta

Campo	Tipo	Descrição
city_code	Integer	Código IBGE da cidade
culture	String	Tipo de cultura agrícola
year	Integer	Ano de referência
productivity	Double	Produtividade em kg/ha
removed	Boolean	Indica se o registro foi removido
created_at	Number	Data de criação do registro, em epoch com segundos decimais
updated_at	Number	Data da última atualização, em epoch com segundos decimais

• 400 - Bad Request

Retornado quando cityCode ou culture não são informados, ou quando culture não corresponde a nenhuma cultura da lista:

{
  "messages": ["message.culture.not-found"]
}

Chaves possíveis: message.cityCode.required, message.culture.required e message.culture.not-found.

• 401 - Unauthorized