Skip to main content
POST
/
api
/
v1
/
grafo
/
sparql
SPARQL Query
curl --request POST \
  --url https://api.example.com/api/v1/grafo/sparql \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>"
}
'
{
  "[]": [
    {}
  ]
}

​
Endpoint

POST /api/v1/grafo/sparql
Execute custom SPARQL queries directly on the shipment knowledge graph. This endpoint provides maximum flexibility for semantic queries.

​
Request Body

​
query
string
required
SPARQL query string. Must be a valid SPARQL SELECT query.

​
Response

Returns an array of result bindings:
​
[]
array
Array of result objects. Keys correspond to the variables in the SELECT clause.

​
Ontology Namespace

The shipment ontology uses the namespace: 
PREFIX onto: <http://jchilon3mas.org/ontologia#>

​
Main Classes

  • onto:Envio - Shipment
  • onto:Cliente - Client
  • onto:Sucursal - Branch office
  • onto:Encomienda - Package
  • onto:Vehiculo - Vehicle

​
Main Properties

​
Shipment Properties

  • onto:tieneCodigoSeguimiento - Tracking code
  • onto:tieneEstado - Status
  • onto:tienePrecio - Price
  • onto:tieneFechaEnvio - Shipment date
  • onto:tieneFechaEntrega - Delivery date
  • onto:enviadoPor - Sent by (client)
  • onto:destinadoA - Addressed to
  • onto:origen - Origin branch
  • onto:destino - Destination branch
  • onto:contieneEncomienda - Contains package
  • onto:transportadoEn - Transported in (vehicle)

​
Client Properties

  • onto:tieneNombre - Name
  • onto:tieneDNI - DNI
  • onto:tieneCorreo - Email
  • onto:tieneTelefono - Phone

​
Branch Properties

  • onto:tieneCiudad - City
  • onto:tieneNombreSucursal - Branch name
  • onto:tieneDireccion - Address

​
Package Properties

  • onto:tienePeso - Weight
  • onto:tieneDimensiones - Dimensions
  • onto:tieneDescripcion - Description

​
Example Queries

​
List All Shipments with Status

curl -X POST http://localhost:8080/api/v1/grafo/sparql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PREFIX onto: <http://jchilon3mas.org/ontologia#> SELECT ?envio ?codigo ?estado WHERE { ?envio a onto:Envio . ?envio onto:tieneCodigoSeguimiento ?codigo . ?envio onto:tieneEstado ?estado . }"
  }'
Response: 
[
  {
    "envio": "http://jchilon3mas.org/envio/42",
    "codigo": "ENV-20260309-ABCD1234",
    "estado": "EN_TRANSITO"
  },
  {
    "envio": "http://jchilon3mas.org/envio/43",
    "codigo": "ENV-20260310-EFGH5678",
    "estado": "DISPONIBLE"
  }
]

​
Find Shipments by Route

curl -X POST http://localhost:8080/api/v1/grafo/sparql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PREFIX onto: <http://jchilon3mas.org/ontologia#> SELECT ?codigo ?estado ?precioWHERE { ?envio onto:tieneCodigoSeguimiento ?codigo . ?envio onto:tieneEstado ?estado . ?envio onto:tienePrecio ?precio . ?envio onto:origen ?origen . ?origen onto:tieneCiudad \"Lima\" . ?envio onto:destino ?destino . ?destino onto:tieneCiudad \"Cusco\" . }"
  }'
Response: 
[
  {
    "codigo": "ENV-20260309-ABCD1234",
    "estado": "EN_TRANSITO",
    "precio": "25.50"
  },
  {
    "codigo": "ENV-20260308-MNOP4567",
    "estado": "DISPONIBLE",
    "precio": "30.00"
  }
]

​
Find Shipments by Client

curl -X POST http://localhost:8080/api/v1/grafo/sparql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PREFIX onto: <http://jchilon3mas.org/ontologia#> SELECT ?codigo ?estado ?destinatario WHERE { ?envio onto:tieneCodigoSeguimiento ?codigo . ?envio onto:tieneEstado ?estado . ?envio onto:destinadoA ?destinatario . ?envio onto:enviadoPor ?cliente . ?cliente onto:tieneNombre \"María García\" . }"
  }'
Response: 
[
  {
    "codigo": "ENV-20260309-ABCD1234",
    "estado": "EN_TRANSITO",
    "destinatario": "Juan Pérez"
  },
  {
    "codigo": "ENV-20260228-YZAB6789",
    "estado": "ENTREGADO",
    "destinatario": "Ana López"
  }
]

​
Find Heavy Packages

curl -X POST http://localhost:8080/api/v1/grafo/sparql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PREFIX onto: <http://jchilon3mas.org/ontologia#> SELECT ?codigo ?peso ?descripcion WHERE { ?envio onto:tieneCodigoSeguimiento ?codigo . ?envio onto:contieneEncomienda ?encomienda . ?encomienda onto:tienePeso ?peso . ?encomienda onto:tieneDescripcion ?descripcion . FILTER (?peso > 5.0) }"
  }'
Response: 
[
  {
    "codigo": "ENV-20260310-EFGH5678",
    "peso": "7.5",
    "descripcion": "Equipo electrónico"
  },
  {
    "codigo": "ENV-20260311-CDEF9012",
    "peso": "10.0",
    "descripcion": "Libros y documentos"
  }
]

​
Count Shipments by Status

curl -X POST http://localhost:8080/api/v1/grafo/sparql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "PREFIX onto: <http://jchilon3mas.org/ontologia#> SELECT ?estado (COUNT(?envio) as ?total) WHERE { ?envio onto:tieneEstado ?estado . } GROUP BY ?estado"
  }'
Response: 
[
  {
    "estado": "EN_TRANSITO",
    "total": "15"
  },
  {
    "estado": "DISPONIBLE",
    "total": "8"
  },
  {
    "estado": "ENTREGADO",
    "total": "42"
  },
  {
    "estado": "PENDIENTE",
    "total": "5"
  }
]

​
SPARQL Query Structure

Basic SPARQL query template: 
PREFIX onto: <http://jchilon3mas.org/ontologia#>

SELECT ?variable1 ?variable2
WHERE {
  # Triple patterns
  ?subject onto:property ?object .
  
  # Filters
  FILTER (?variable > value)
}
ORDER BY ?variable1
LIMIT 10

​
Advanced Features

​
OPTIONAL Patterns

Query optional properties: 
PREFIX onto: <http://jchilon3mas.org/ontologia#>
SELECT ?codigo ?fechaEntrega
WHERE {
  ?envio onto:tieneCodigoSeguimiento ?codigo .
  OPTIONAL { ?envio onto:tieneFechaEntrega ?fechaEntrega . }
}

​
FILTER Expressions

Filter results: 
FILTER (?precio > 50.0)
FILTER (regex(?ciudad, "Lima", "i"))
FILTER (?estado = "EN_TRANSITO")

​
Aggregation

SELECT ?ciudad (AVG(?precio) as ?precioPromedio)
WHERE {
  ?envio onto:tienePrecio ?precio .
  ?envio onto:destino ?sucursal .
  ?sucursal onto:tieneCiudad ?ciudad .
}
GROUP BY ?ciudad
Only SELECT queries are supported. CONSTRUCT, ASK, and DESCRIBE queries are not currently available.
Invalid SPARQL syntax will result in a 500 error. Validate your queries before sending them to the API.

​
Error Handling

Invalid query: 
{
  "error": "SPARQLException",
  "message": "Syntax error in SPARQL query"
}

​
Performance Tips

  1. Use LIMIT to restrict result size
  2. Be specific with triple patterns
  3. Use FILTER early in the WHERE clause
  4. Avoid expensive operations like OPTIONAL on large datasets

​
Query Examples Repository

For more query examples, refer to the ontology documentation at: 
http://jchilon3mas.org/ontologia/queries

Build docs developers (and LLMs) love

Get started for freeTalk to us