Join the chat at DOI Build Status

grlc, the git repository linked data API constructor, automatically builds Web APIs using SPARQL queries stored in git repositories.

What is grlc?

grlc is a lightweight server that takes SPARQL queries (stored in a GitHub repository, in your local filesystem, or listed in a URL), and translates them to Linked Data Web APIs. This enables universal access to Linked Data. Users are not required to know SPARQL to query their data, but instead can access a web API.

Quick tutorial

For a quick usage tutorial check out our wiki walkthrough and list of features.


grlc assumes that you have a collection of SPARQL queries as .rq files (like this). grlc will create an API operation per such a SPARQL query/.rq file. Your queries can include special decorators to add extra functionality to your API.

Query location

grlc can load your query collection from different locations: from a GitHub repository (api-git), from local storage (api-local), and from a specification file (api-url). Each type of location has specific features and is accessible via different paths. However all location types produce the same beautiful APIs.

From a GitHub repository

API path: http://grlc-server/api-git/<user>/<repo>

grlc can build an API from any Github repository, specified by the GitHub user name of the owner (<user>) and repository name (<repo>).

For example, assuming your queries are stored on a Github repo:, point your browser to the following location

grlc can make use of git's version control mechanism to generate an API based on a specific version of queries in the repository. This can be done by including the commit sha in the URL path (http://grlc-server/api-git/<user>/<repo>/commit/<sha>), for example:

grlc can also use a subdirectory inside your Github repo. This can be done by including a subdirectory in the URL path (http://grlc-server/api-git/<user>/<repo>/subdir/<subdir>).

From local storage

API path: http://grlc-server/api-local/

grlc can generate an API from a local directory in the computer where your grlc server runs. You can configure the location of this folder in your grlc server configuration file. See also how to install and run your own grlc instance.

From a specification file

API path: http://grlc-server/api-url/?specUrl=<specUrl>

grlc can generate an API from a yaml specification file accessible on the web.

For example, assuming your queries are listed on spec file:, point your browser to the following location

Specification file syntax

A grlc API specification file is a YAML file which includes the necessary information to create a grlc API, most importantly a list of URLs to decorated and HTTP-dereferenceable SPARQL queries. This file should contain the following fields

For example:

title: Title of my API
  name: Contact Name

grlc generated API

The API paths of all location types point to the generated swagger-ui style API documentation. On the API documentation page, you can explore available API calls and execute individual API calls.

You can also view the swagger spec of your API, by visiting <API-path>/spec/, for example:

grlc query execution

When you call an API endpoint, grlc executes the SPARQL query for that endpoint by combining supplied parameters and decorators.

There are 4 options to specify your own endpoint:

The endpoint call will return the result of executing the query as a json representation of rdflib.query.QueryResult (for other result formats, you can use content negotiation via HTTP Accept headers). For json responses, the schema of the response can be modified by using the #+ transform: decorator.

Decorator syntax

Special decorators are available to make your swagger-ui look nicer and to increase functionality. These are provided as comments at the start of your query file, making it still syntactically valid SPARQL. All decorators start with #+, for example:

#+ decorator_1: decorator value
#+ decorator_1: decorator value

  ?s ?p ?o .

The following is a list of available decorators and their function:


Creates a summary of your query/operation. This is shown next to your operation name in the swagger-ui.


#+ summary: This is the summary of my query/operation

Example query and the equivalent API operation.


Creates a description of your query/operation. This is shown as the description of your operation in the swagger-ui.


#+ description: Extended description of my query/operation.

Example query and the equivalent API operation.


Specifies a query-specific endpoint.


#+ endpoint:

Example query and the equivalent API operation.


Paginates the results in groups of (for example) 100. Links to previous, next, first, and last result pages are provided as HTTP response headers to avoid polluting the payload (see details here)


#+ pagination: 100

Example query and the equivalent API operation.


Indicates the HTTP request method (GET and POST are supported).


#+ method: GET

Example query and the equivalent API operation.


Assign tags to your query/operation. Query/operations with the same tag are grouped together in the swagger-ui.


#+ tags:
#+   - firstTag
#+   - secondTag

Example query and the equivalent API operation.


Indicates which parameters of your query/operation should get enumerations (and get dropdown menus in the swagger-ui) using the given values from the SPARQL endpoint. The values for each enumeration variable can also be specified into the query decorators to save endpoint requests and speed up the API generation.


#+ enumerate:
#+   - var1:
#+     - value1
#+     - value2

Example query and the equivalent API operation.

Notice that these should be plain variable names without SPARQL/BASIL conventions (so var1 instead of ?_var1_iri)


Allows/disallows the endpoint parameter from being provided as a URL parameter (allowed by default).


#+ endpoint_in_url: False

Example query and the equivalent API operation.


Allows query results to be converted to the specified JSON structure, by using SPARQLTransformer syntax.


#+ transform: {
#+     "key": "?p",
#+     "value": "?o",
#+     "$anchor": "key"
#+   }

Example query and the equivalent API operation.

Example APIs

Check these out:

You'll find the sources of these and many more in GitHub

Use this GitHub search to see examples from other grlc users.

Install and run

You can use grlc in different ways:

More details for each of these options are given below.

The easiest way to use grlc is by visiting and using this service to convert SPARQL queries into a RESTful API. Your queries can be stored on a github repo or can be listed on a specification file.


To run grlc via docker, you'll need a working installation of docker. To deploy grlc, just pull the latest image from Docker hub. :

docker run -it --rm -p 8088:80 clariah/grlc

The docker image allows you to setup several environment variable such as GRLC_SERVER_NAME GRLC_GITHUB_ACCESS_TOKEN and GRLC_SPARQL_ENDPOINT:

docker run -it --rm -p 8088:80 -e -e GRLC_GITHUB_ACCESS_TOKEN=xxx -e GRLC_SPARQL_ENDPOINT= -e DEBUG=true clariah/grlc


If you want to run grlc locally or use it as a library, you can install grlc on your machine. Grlc is registered in PyPi so you can install it using pip.


grlc has the following requirements:

pip install

Once the base requirements are satisfied, you can install grlc like this:

pip install grlc

Once grlc is installed, you have several options:

Standalone server

grlc includes a command line tool which you can use to start your own grlc server:


Using a WSGI server

You can run grlc using a WSGI server such as gunicorn as follows:

gunicorn grlc.server:app

If you want to use your own gunicorn configuration, for example

workers = 5
worker_class = 'gevent'
bind = ''

Then you can run it as:

gunicorn -c grlc.server:app

Note: Since gunicorn does not work under Windows, you can use waitress instead:

waitress-serve --port=8088 grlc.server:app

If you want to run grlc at system boot as a service, you can find example upstart scripts at upstart/

grlc library

You can use grlc as a library directly from your own python script. See the usage example to find out more.

grlc server configuration

Regardless of how you are running your grlc server, you will need to configure it using the config.ini file. Have a look at the example config file to see how it this file is structured.

The configuration file contains the following variables:

GitHub access token

In order for grlc to communicate with GitHub, you'll need to tell grlc what your access token is:

  1. Get a GitHub personal access token. In your GitHub's profile page, go to Settings, then Developer settings, Personal access tokens, and Generate new token
  2. You'll get an access token string, copy it and save it somewhere safe (GitHub won't let you see it again!)
  3. Edit your config.ini or docker-compose.yml as value of the environment variable GRLC_GITHUB_ACCESS_TOKEN.


grlc needs you to continue bringing Semantic Web content to developers, applications and users. No matter if you are just a curious user, a developer, or a researcher; there are many ways in which you can contribute:

Check our contributing guidelines for these and more, and join us today!

If you cannot code, that's no problem! There's still plenty you can contribute:

Related tools

This is what grlc users are saying

Quotes from grlc users:

A cool project that can convert a random SPARQL endpoint into an OpenAPI endpoint

It enables us to quickly integrate any new API requirements in a matter of seconds, without having to worry about configuration or deployment of the system

You can store your SPARQL queries on GitHub and then you can run your queries on your favourite programming language (Python, Javascript, etc.) using a Web API (including swagger documentation) just as easily as loading data from a web page

Contributors: Albert Meroño, Rinke Hoekstra, Carlos Martínez

Copyright: Albert Meroño, VU University Amsterdam
License: MIT License (see LICENSE.txt)

Academic publications