nvdb-api-client

Open source Java client library for use with the NVDB REST API v3.

Support or feedback: Issue on this repo or on Gitter

API URL

Base URL for the API is https://nvdbapiles-v3.atlas.vegvesen.no

Artifact

This artifact will be published to Maven Central upon releases.

Gradle

def nvdbVersion = "1.17.2"
def slfVersion = "1.7.30"

dependencies {
    compile "no.vegvesen.nvdb:nvdb-read-api-v3-client:$nvdbVersion"
    compile "javax.activation:activation:1.1"
    compile "org.slf4j:slf4j-api:$slfVersion"
    compile "org.slf4j:slf4j-simple:$slfVersion"
}

Maven

<properties>
    <nvdb.version>1.17.2</nvdb.version>
    <slf.version>1.7.30</slf.version>
</properties>

<dependencies>
    <dependency>
        <groupId>no.vegvesen.nvdb</groupId>
        <artifactId>nvdb-read-api-v3-client</artifactId>
        <version>${nvdb.version}</version>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>${slf.version}</version>
    </dependency>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-simple</artifactId>
        <version>${slf.version}</version>
    </dependency>
</dependencies>

Getting started

Using the client is very simple. All it takes is a couple of lines of code.

Authentication

This is a completely open API, but some featuretypes are restricted and need authentication and authorization. We strongly encourage using the X-Client-Name header because it helps us gather statistics which we use to improve the API.

Example

To start using the library simply instantiate the factory. It takes three arguments:

Base URL for the API
Value for request header X-Client-Name

// First, create factory
ClientFactory factory = new ClientFactory("https://nvdbapiles-v3.atlas.vegvesen.no", "nvdb-read-api-v3-client");
// Then, create your client. Typically, there's one per root endpoint   
RoadObjectClient client = factory.getRoadObjectClient();

// Example single object download
RoadObject ro = client.getRoadObject(534, 1);

// Remember to close your factory when you're done using it
factory.close();

Please note that when the factory is closed all clients created by it will also be closed. So the following code will not work

RoadObjectClient client;
try (ClientFactory factory = new ClientFactory("https://nvdbapiles-v3.atlas.vegvesen.no", "nvdb-read-api-v3-client")) {
    client = factory.createRoadObjectClient();
}

// Won't work because client is closed after the try-with-resources block.
RoadObject ro = client.getRoadObject(534, 1);

Setting timeouts for Jersey client.

To set a connect and read timeout for the nvdb-api-client. An instance of ClientConfiguration can be added when creating the ClientFactory

// Add a read timeout of 5000 millis and connect timeout of 1000 millis
ClientConfiguration clientConfig = 
   ClientConfigurationBuilder.builder()
      .withReadTimeout(5000)
      .withConnectTimeout(1000)
      .build();

// Create a factory with timeout settings.
ClientFactory factory = new ClientFactory("https://nvdbapiles-v3.atlas.vegvesen.no", "nvdb-read-api-v3-client", clientConfig);

Simple setup

To use the client in your project, you should:

Add the gradle or maven code to your project build file (pom.xml for maven projects);
Fill in your preferred version at $version (maven versions are available here: https://search.maven.org/artifact/no.vegvesen.nvdb/nvdb-read-api-v3-client);
Add some of the example code and run it.

How to build

The repo contains the Gradle wrapper. The client is built running:

// Simple compilation 
./gradlew build

// Publish to your Maven local
./gradlew publishToMavenLocal

EvenAR/nvdb-api-client