nomearEntrar

Integração

API do Nomear

Conecte o sistema da sua organização às listas do Nomear. A API entrega em JSON as mesmas listas que a organização vê na tela: as dela, as Referências do Nomear e as que outras organizações abriram para ela.

Uma chave por sistema

A chave é da organização, não de uma pessoa: quem a criou pode sair que a integração continua.

Só leitura

A chave lê o que a organização lê no Nomear. Nada é alterado pelo caminho da API.

Chave do termo que não muda

Cada termo tem uma chave fixa (value). Guarde ela no seu sistema: o nome pode mudar, a chave não.

Começar

  1. Na página da organização no Nomear (menu Organização), seção Integrações (API), clique em Nova chave. Dê o nome do sistema que vai usar a chave e escolha a validade (1 ano por padrão). Só a administração do Nomear e os editores da organização geram chaves.
  2. Copie a chave (começa com nmr_). Ela aparece uma vez só: guarde na configuração do sistema ou num cofre de senhas.
  3. Teste. A resposta diz de qual organização é a chave e até quando ela vale.
curl -H "Authorization: Bearer nmr_SUA_CHAVE" https://nomear-staging.terrakrya.com/api/v1

Autenticação

Todo pedido leva a chave no cabeçalho Authorization, no formato Bearer nmr_…. Endereço base de todas as rotas:

https://nomear-staging.terrakrya.com/api/v1
  • A chave é para o servidor do seu sistema. Não coloque em página aberta no navegador, em aplicativo instalado nem em código público: quem tiver a chave lê o que a organização lê.
  • Gere uma chave para cada sistema. Se uma vazar, revogue só ela na página da organização: o acesso acaba na hora.
  • Antes de a chave vencer, gere outra, troque no sistema e revogue a antiga.
  • A interface do Nomear e a API são separadas: o login da tela não abre a API, e a chave não abre a tela.

Rotas

Todas são GET e respondem JSON (as de planilha, o arquivo). {id} é o id da lista, que aparece em /vocabularies e nunca muda.

GET/A chave

Organização dona da chave, nome e validade. Bom para testar a configuração.

GET/vocabulariesListas

Todas as listas que a organização lê: as dela, as Referências do Nomear e as que outras organizações abriram para ela.

ParâmetroTipoO que é
qstringParte do título, sem acento nem caixa.
modelstringSó listas deste modelo (model.slug).
archived"true" | "false" | "all"false (padrão) esconde as arquivadas; true só elas; all todas.
GET/vocabularies/{id}Uma lista

Dados da lista e os atributos que os termos têm.

GET/vocabularies/{id}/termsTermos

Termos da lista, em páginas, na ordem da lista. Com at, como estavam numa versão ou data.

ParâmetroTipoO que é
qstringCasa com o rótulo ou um sinônimo, sem acento nem caixa.
active"true" | "false" | "all"true (padrão) só os em uso; false só os inativos; all todos.
limitintegerTermos por página (1 a 500, padrão 100).
cursorstringO nextCursor da página anterior.
atstringLer como estava numa versão (v3) ou num instante (ISO 8601 com fuso, 2026-09-30T23:59:59-03:00). Ausente ou atual: estado atual.
GET/vocabularies/{id}/terms/{value}Um termo

Um termo pela chave, em uso ou inativo. Termo inativo vem com replacedBy quando foi substituído.

GET/vocabularies/{id}/searchBusca

Termos em uso que casam com o texto: para autocompletar um campo no seu sistema.

ParâmetroTipoO que é
q *stringTexto digitado: casa com o rótulo ou um sinônimo; quem começa com ele vem primeiro.
limitintegerQuantos termos (1 a 20, padrão 20).
GET/vocabularies/{id}/changesO que mudou

Termos criados, alterados, desativados ou com relações mudadas desde since, já no estado atual. Sem since, todos os termos.

ParâmetroTipoO que é
sincestringO nextSince da sincronização anterior. Ausente: todos os termos (primeira sincronização).
limitintegerTermos por página (1 a 500, padrão 100).
cursorstringO nextCursor da página anterior.
GET/vocabularies/{id}/versionsVersões

Versões salvas da lista, da mais recente à mais antiga.

GET/vocabularies/{id}/export/csvPlanilha CSV

A lista em CSV (separador ;, decimal com vírgula), no mesmo formato da exportação da tela.

ParâmetroTipoO que é
atstringLer como estava numa versão (v3) ou num instante (ISO 8601 com fuso, 2026-09-30T23:59:59-03:00). Ausente ou atual: estado atual.
includeInactive"0" | "1" | "true" | "false"1 inclui os termos inativos.
GET/vocabularies/{id}/export/xlsxPlanilha Excel

A lista em XLSX, no mesmo formato da exportação da tela.

ParâmetroTipoO que é
atstringLer como estava numa versão (v3) ou num instante (ISO 8601 com fuso, 2026-09-30T23:59:59-03:00). Ausente ou atual: estado atual.
includeInactive"0" | "1" | "true" | "false"1 inclui os termos inativos.

Exemplos:

curl -H "Authorization: Bearer nmr_SUA_CHAVE" "https://nomear-staging.terrakrya.com/api/v1/vocabularies"
curl -H "Authorization: Bearer nmr_SUA_CHAVE" "https://nomear-staging.terrakrya.com/api/v1/vocabularies/ID_DA_LISTA/terms?limit=100"
curl -H "Authorization: Bearer nmr_SUA_CHAVE" "https://nomear-staging.terrakrya.com/api/v1/vocabularies/ID_DA_LISTA/search?q=altamira"

Páginas. As rotas de termos devolvem até 500 termos por vez (limit) e um nextCursor. Para a próxima página, repita o pedido com cursor=<nextCursor>; quando ele vier null, acabou.

Documento OpenAPI. A descrição completa, para importar no Postman ou no Insomnia ou gerar um cliente, está em https://nomear-staging.terrakrya.com/api/v1/openapi (aberto, sem chave).

O termo

Cada termo vem assim. Os atributos dependem do modelo da lista (veja attributes em /vocabularies/{id}).

{
  "value": "altamira",
  "label": "Altamira",
  "code": "1500602",
  "synonyms": [
    "Altamira (PA)"
  ],
  "active": true,
  "replacedBy": null,
  "broader": {
    "value": "pa",
    "label": "Pará",
    "active": true
  },
  "related": [
    {
      "vocabularyId": "7d1f2c4e-8a90-4b6f-9c3d-2e5a7b8c9d01",
      "vocabularySlug": "terras-indigenas",
      "vocabularyTitle": "Terras indígenas",
      "value": "ti_arara",
      "label": "Arara",
      "active": true
    }
  ],
  "coordinates": {
    "latitude": -3.2033,
    "longitude": -52.2064
  },
  "attributes": {},
  "sortOrder": null,
  "createdAt": "2026-09-15T12:00:00.000Z",
  "updatedAt": "2026-10-29T10:00:00.000Z"
}
CampoTipoO que é
valuestringChave do termo: única na lista e nunca muda. É ela que o seu sistema guarda.
labelstringNome preferido do termo.
codestring | nullCódigo opcional (por exemplo, o código do IBGE).
synonymsarray<string>Outros nomes: grafias, siglas, nomes locais. A busca também casa por eles.
activebooleanEm uso. Termo inativo continua respondendo, mas não deve ser oferecido em cadastros novos.
replacedByobject | nullTermo da mesma lista que substitui este, quando inativo.
broaderobject | null"Pertence a": termo da lista indicada em broaderVocabulary.
relatedarray<object>"Relacionado a": termos ligados a este, de qualquer lista.
coordinatesobject | nullPonto no mapa em graus decimais, só em listas com mapa.
attributesobjectAtributos do modelo da lista (ver attributes da lista). Atributo de referência vem como { value, label, active }.
sortOrderinteger | nullPosição fixa na lista, quando definida.
createdAtstring (ISO 8601)Criação do termo.
updatedAtstring (ISO 8601)Última alteração do termo ou das relações dele.
Campos da lista (/vocabularies/{id})
CampoTipoO que é
idstring (uuid)Identificador da lista, usado nas rotas. Nunca muda.
slugstringIdentificador legível (único dentro da organização dona).
titlestringTítulo da lista.
descriptionstring | nullDescrição da lista.
kind"reference" | "organization"reference: Referência do Nomear, com dados oficiais. organization: lista de uma organização.
organizationobject | nullOrganização dona; null em Referência do Nomear.
ownedByYoubooleanA lista é da organização da chave.
modelobjectModelo da lista: define os atributos dos termos.
sourceobject | nullFonte dos dados (nome, endereço, versão, licença).
basedOnobject | nullReferência do Nomear de onde a lista escolhe termos.
hasCoordinatesbooleanOs termos têm ponto no mapa.
broaderVocabularyobject | nullLista a que os termos "pertencem" (broader de cada termo). isSelf: hierarquia dentro da própria lista.
archivedbooleanLista arquivada: não recebe mais alterações.
termCountintegerTermos da lista, ativos e inativos.
activeTermCountintegerTermos em uso.
latestVersionobject | nullÚltima versão salva, se houver.
lastTermChangeAtstring (ISO 8601) | nullÚltima alteração de algum termo da lista.
createdAtstring (ISO 8601)Criação da lista.
updatedAtstring (ISO 8601)Última alteração dos dados da lista (título, estrutura).
attributesarray<object>Atributos dos termos desta lista.

Manter o seu sistema em dia

  1. Na primeira vez, peça /vocabularies/{id}/changes sem since: vêm todos os termos da lista, em páginas. Grave cada um pela chave (value): insere se não existe, atualiza se existe.
  2. Guarde o nextSince da resposta (é o mesmo em todas as páginas).
  3. De tempos em tempos (por exemplo, a cada hora), peça de novo com since=<nextSince>: vêm só os termos criados, alterados ou desativados desde então, e os que ganharam ou perderam uma relação. Grave e guarde o novo nextSince.
  • Nenhum termo é apagado no Nomear: termo que sai de uso vem com active: false e, se foi substituído, com replacedBy. Use isso para corrigir os registros antigos do seu sistema.
  • O mesmo termo pode vir em duas sincronizações seguidas. Gravar pela chave resolve.
  • Os rótulos dos termos apontados (broader, related, replacedBy, atributos de referência) são os do momento da leitura. Quando um termo apontado muda, ele vem na sincronização da lista dele, não na dos termos que apontam para ele: guarde as chaves e tire o rótulo da lista de origem.
  • Se o cursor de uma página se perder ou vier corrompido, a resposta é 400: recomece com o último nextSince que você guardou.
import requests

BASE = "https://nomear-staging.terrakrya.com/api/v1"
HEADERS = {"Authorization": "Bearer nmr_SUA_CHAVE"}

def sincronizar(lista, since=None):
    """Traz o que mudou na lista desde `since` (None = tudo) e devolve o próximo since."""
    params = {"limit": 500}
    if since:
        params["since"] = since
    while True:
        url = f"{BASE}/vocabularies/{lista}/changes"
        r = requests.get(url, headers=HEADERS, params=params, timeout=30)
        r.raise_for_status()
        pagina = r.json()
        for termo in pagina["items"]:
            salvar(termo)  # inserir ou atualizar pela chave termo["value"]
        if not pagina["nextCursor"]:
            return pagina["nextSince"]  # guarde para a próxima vez
        params = {"limit": 500, "cursor": pagina["nextCursor"]}
Campos da resposta de /changes
CampoTipoO que é
itemsarray<object>
nextCursorstring | nullEnvie em cursor para a próxima página; null quando acabou.
totalintegerQuantos termos atendem ao pedido, somando todas as páginas.
sincestring (ISO 8601) | nullO since pedido, como foi enviado; null = primeira sincronização (todos os termos).
nextSincestring (ISO 8601)Guarde e envie como since na próxima sincronização. Vem igual em todas as páginas.

Versões e datas

A organização pode salvar versões de uma lista. O seu sistema pode ficar preso a uma versão enquanto a lista continua mudando, ou ler a lista como estava numa data. Nas rotas de termos e de planilha, use at=v3 (versão) ou at=2026-09-30T23:59:59-03:00 (data e hora com fuso). As versões de cada lista estão em /vocabularies/{id}/versions.

curl -H "Authorization: Bearer nmr_SUA_CHAVE" "https://nomear-staging.terrakrya.com/api/v1/vocabularies/ID_DA_LISTA/terms?at=v3"

Limites e erros

Cada chave pode fazer até 120 pedidos por minuto. Os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining mostram quanto resta. Erros vêm em JSON, com o código HTTP e uma mensagem em português: { "statusCode": 404, "message": "Vocabulário não encontrado." }.

CódigoQuando
400Parâmetro inválido. A mensagem diz qual.
401Chave ausente, inválida, vencida ou revogada.
403A organização da chave está arquivada.
404Lista ou termo não existe, ou a organização não lê essa lista.
429Mais de 120 pedidos por minuto com a mesma chave. Espere os segundos do cabeçalho Retry-After.
Nomear — repositório de vocabulários controlados.