Table of Contents Navbar
cURL

API Introduction

If you're looking to interact with the Namara API, you've come to the right place. This guide will cover instructions and conventions for using our API, with language-specific examples.

Our REST API

The Namara API is a REST-based service that accepts and returns JSON in most cases (we'll cover response formats later). Requests should be made to:

https://:namara_api_host/v0/:endpoint

Unless indicated otherwise, the Namara API host is api.namara.io, which will be used throughout the documentation.

The responses will be outlined for each endpoint.

GET Generic Endpoint

https://api.namara.io/v0/:endpoint

In the code column on the right is a generic endpoint, and the foundation of almost every call to our API. The chart below displays standard response codes:

Response Description
200: OK Success
202: Accepted A background job has successfully been triggered - continue polling for details
401: Unauthorized The API key you provided doesn't correspond to any user
403: Forbidden User is not authorized to make that request
422: Unprocessable Entity The server was unable to save the document; there will be more details in the full response body
429: Too Many Requests User has exceeded the monthly maximum for requests or downloads (see Rate Limiting)

API Keys

Three kinds of API Keys can be created for accessing the Namara API - Organization Keys, Project Keys, and Personal Keys. This is an overview of managing all three types, and we'll outline the different use cases for each.

Organization API Keys

For any non-personal Organization, visit the "Settings" tab and create API Keys for that Organization. Calls made with this API Key will be limited to Data Sets and Projects that your Organization has access to.

Project API Keys

For any project, visit the "Settings" tab and create API Keys for yourself for that Project. Calls made with this API Key will be limited to Data Sets that your Project has access to.

Personal API Keys

The Personal Namara API Key can be obtained by clicking on the Organization tab at the bottom of the left sidebar, then clicking "Account Settings". Copy this from the "API Key" tab and use it for any API calls.

Rate Limiting

Users are limited to 10,000 requests per month, as well as 100 data set downloads per month. If you exceed this limit, the API will return status: 429. If you find yourself meeting the limits, contact your account manager or email us to find a solution.

Making Requests

Parameter Authentication

curl -XGET https://api.namara.io/v0/data_sets/:data_set_id?api_key=:YOUR_API_KEY

  or

curl -i \
-H "Content-Type: application/json" \
-H "X-API-Key: {YOUR_API_KEY}" \
-X POST \
-d '{"query":"..."}' \
https://api.namara.io/v0/query.:format

Append the key as api_key to any request body (either GET or POST) as long as it is included in the parameters.

Header Authentication

The API Key can be sent in the request headers as X-API-Key. Append the key to the headers by adding "X-API-Key: {YOUR_API_KEY}"

Testing Authentication

Here's how to verify your API Key:

GET Verify API Key

Ping the API at http://api.namara.io/v0/users/verify_token to ensure that the API token is valid for the user.

1) { "status": true }

2) { "status": false }

Response Description
200: OK The API Key is valid (example 1)
422: Unprocessable Entity API does not correspond to any user (example 2)

Data API

https://:namara_api_host/v0/data_sets/:data_set_id/data/:version

Each data set can be accessed at the API URL. In Namara, click on the "API Info" tab when viewing a data set to see all information regarding ID, version, and properties.

GET Data Query

https://api.namara.io/v0/data_sets/:data_set_id/data/:version

This endpoint is used for creating selection and aggregation views on a single data set. For full SQL access to the Namara catalog, see the Query API.

Path Parameters Type Description
data_set_id (required) string UUID for accessing the data set
version (required) string Version identifier, eg: en-0
Query Parameters Type Description
result_format string Query response format: CSV, JSON, or GeoJSON (default is JSON)
geometry_format string Either WKT or GeoJSON for all geometry values (default is GeoJSON)
geojson_feature_key string Property name to use as geometry when rendering GeoJSON
limit integer Number of rows to return - the default value is also the maximum: 250 (see Pagination)
offset integer Results will be returned starting at the row number specified (see Pagination)
select string Comma-separated list of column names to return
order string Specify the order of the returned results (see Ordering)
where string Conditions for performing query (see Conditions)

Formats, Pagination, & Ordering

Results Format

The Namara Data API produces results in different formats, JSON, CSV, or GeoJSON, depending on the value you pass into the result_format parameter in your query. In examples of results, you'll see three buttons above the code block which will show example results in your preferred format. Here's how they look:

  {
    "results":[
      {
        "c0":"format",
        "c1":"example"
      },
      ...
    ]
  }
  c0,c1
  format,example
  {
    "type":"GeojsonResponseFormat",
    "features":[
      {
        "type":"Feature",
        "geometry":{
          "type":"Point",
          "coordinates": [ -79.4, 43.7 ]
        },
        "properties":{
          "c0":"format",
          "c1":"example"
        }
      },
      ...
    ]
  }

Pagination

Each query response is limited to 250 results. To view the entire response, either use the export endpoint to render the results of the query, or use limit and offset arguments to paginate over results, until no more values are found.

Ordering

...&order=p0 ASC

Pass in either ASC or DESC after specifying a column to see results in ascending or descending order, respectively.

Conditions

The where argument supports a number of comparison operators and geospatial functions:

Symbol Alias Description Use
= eq Returns an exact, case-sensitive match of the value p0=100 p3 eq '2015-01-06'
!= neq Returns an exact, case-sensitive match of the value p0!=50 p3 neq '2016-07-16'
> gt Works for numerical, date and datetime values p0>100 p0 gt '2010-01-01'
>= gte Works for numerical, date and datetime values p0>=75 p0 gte '2010-01-01'
< lt Works for numerical, date and datetime values p0<200 p0 lt '2018-04-01'
<= lte Works for numerical, date and datetime values p0<=150 p0 lte '2017-11-01'
IS Only works for boolean values p1 IS true p1 IS NULL
IS NOT Only works for boolean values p1 IS NOT true p1 IS NOT NULL
LIKE % = wildcard, case-insensitive p2 LIKE '%foo%'
NOT LIKE % = wildcard case-insensitive p2 NOT LIKE '%foo%'
IN Works for values in a specified list of items p0 IN (100, 'foo', true)

Operator Examples

1) https://api.namara.io/v0/data_sets/057d7914-839e-4625-b8f8-2aa109f11e5a/data/en-3?api_key=:YOUR_API_KEY&where=co2_emissions_g_km<200
or
https://api.namara.io/v0/data_sets/057d7914-839e-4625-b8f8-2aa109f11e5a/data/en-3?api_key=:YOUR_API_KEY&where=co2_emissions_g_km lt 200

2a) https://api.namara.io/v0/data_sets/057d7914-839e-4625-b8f8-2aa109f11e5a/data/en-3?api_key=:YOUR_API_KEY&where=make IN ("CHEVROLET","CADILLAC")

2b) https://api.namara.io/v0/data_sets/057d7914-839e-4625-b8f8-2aa109f11e5a/data/en-3?api_key=:YOUR_API_KEY&where=make="CHEVROLET" OR make="CADILLAC"

3) https://api.namara.io/v0/data_sets/057d7914-839e-4625-b8f8-2aa109f11e5a/data/en-3?api_key=:YOUR_API_KEY&where=(make="CHEVROLET" OR make="CADILLAC") AND (fuel_consumption_city_l_100km<=12 AND fuel_consumption_hwy_l_100km<=9)

  1. List all vehicles with CO2 emissions less than 200g/km

  2. a) Get fuel consumption ratings for all Cadillac and Chevrolet vehicles

    b) The same operation with boolean operators

  3. List all Cadillac and Chevrolet vehicles with good city and highway mileage

Example 3 is a more complex query with multiple conditions while explicitly specifying the evaluation order.

Geospatial Operators

Data sets will commonly contain latitude and longitude as properties.

The where condition query parameter supports some geospatial functions for querying data sets.

Geospatial Operator Examples

1) ...&where=nearby(p3, 43.653226, -79.3831843, 10km)

2) ...&where=bbox(p3, 43.5810245, -79.639219, 43.8554579, -79.11689699)
  1. Returns all rows in which the value in the specified column is within radius distance of the point specified by latitude and longitude.

  2. Returns all rows in which the value in the specified column lies within the bounding box created by the two coordinates.

GET Export

Exporting is almost identical to the Data Query endpoint, with the difference being that the complete result of the query will be saved to a file, and that file will be served up.

Request

https://api.namara.io/v0/data_sets/:data_set_id/data/:version/export

Export path and query parameters look a lot like the parameters for accessing the data set. Let's look at the requests you can make:

Path Parameters Type Description
data_set_id (required) string UUID for accessing the data set
version (required) string Version identifier, eg: en-0
Query Parameters Type Description
result_format string Query response format: CSV, JSON, or GeoJSON (default is JSON)
geometry_format string Either WKT or GeoJSON for all geometry values (default is GeoJSON)
geojson_feature_key string Property name to use as geometry when rendering GeoJSON
compress_with string Compression options for final export (see Compression Options)
limit integer Number of rows to export
offset integer Results will be returned starting at the row number specified (see Pagination)
select string Comma-separated list of column names to return
order string Specify the order of the returned results (see Ordering)
where string Conditions for performing query (see Conditions)

Responses

1)
  {
    "message": "Exported",
    "url": "<url to file>",
    "compressed_with": "none"
  }

2)
  { "message": "Pending" }

3)
  {
    "message": "Failed",
    "error_message": "<reason for error>"
  }
Response Description
200: OK When the export has finished and redirect is not set (example 1)
202: Accepted When the export has begun (example 2)
422: Unprocessable Entity Failed to export (example 3)

GET Aggregate

Use aggregation functions to retrieve data set-level information.

Request

https://api.namara.io/v0/data_sets/:data_set_id/data/:version/aggregation

Parameter Type Description
data_set_id (required) string UUID for accessing the data set
version (required) string Version identifier, eg. en-0
operation (required) string Operation function to perform (see Operations)
where string Conditions for performing query (see Conditions)

Operations

Function Description Use
count The number of rows of data. Using * will count all rows - specifying a property will only count non-null rows for that property. count(*) count(p0)
sum The sum of all values in a column sum(p0)
avg The average of all values in a column avg(p0)
min The minimum value in a column min(p0)
max The maximum value in a column max(p0)

Operator Examples

1) https://api.namara.io/v0/data_sets/057d7914-839e-4625-b8f8-2aa109f11e5a/data/en-3/aggregation?api_key=:YOUR_API_KEY&operation=avg(co2_emissions_g_km)&where=make="CADILLAC"

2) https://api.namara.io/v0/data_sets/057d7914-839e-4625-b8f8-2aa109f11e5a/data/en-3/aggregation?api_key=:YOUR_API_KEY&operation=min(co2_emissions_g_km)&where=make="CADILLAC"

3) https://api.namara.io/v0/data_sets/057d7914-839e-4625-b8f8-2aa109f11e5a/data/en-3/aggregation?api_key=:YOUR_API_KEY&operation=count(*)&where=make="CADILLAC"

  1. Reveals the average CO2 emissions of Cadillac vehicles

  2. Reveals the Cadillac vehicle with the least CO2 emission

  3. Reveals all the Cadillac vehicles

Query API (beta)

While the Data API allows query behaviour over a single data set, the Query API allows broader control over the Namara data catalog. This is a new API that will eventually replace the Data API. We wrote NiQL (Namara.io Query Language) to view, aggregate, and join data sets. It's very similar to SQL, so it's easy to manipulate.

GET Meta

https://api.namara.io/v0/query/meta

{
  "query_limit_maximum": 250,
  "formats": ["geojson", "csv", "json"],
  "default_format": "json"
}

This endpoint provides the meta information for querying this Namara instance. It includes the limit per query, the supported formats, and the default format if none is specified. This information may differ, depending on which deployment of Namara you're using.

POST Query

https://api.namara.io/v0/query.:format

A call here dispatches a query and returns the result.

Request

Parameter Type Description
format string Query response format: CSV, JSON, or GeoJSON (default is JSON)
project_id string Project ID to use for subscription lookup. If not provided, it is inferred from API Key
organization_id string Organization ID to use for subscription lookup. If not provided, it is inferred from API Key
query (required) string NiQL query string
geojson_feature_key (may be required) string Property name to use as geometry when rendering GeoJSON

The geojson_feature_key is required if the requested format is GeoJSON - otherwise, it is not needed.

Responses

200: OK

Query executed successfully.

  {
    "results":[
      {
        "c0":"foo",
        "c1":22,
        "c2":"xx",
        "c3":"POINT (-79.4 43.7)"
      },
      ...
    ]
  }
  c0,c1,c2,c3
  foo,22,xx,POINT (-79.4 43.7)
  bar,66,yy,POINT (-78.4 42.7)
  baz,11,xx,POINT (-70.4 35.7)
  {
    "type":"FeatureCollection",
    "features":[
      {
        "type":"Feature",
        "geometry":{
          "type":"Point",
          "coordinates": [ -79.4, 43.7 ]
        },
        "properties":{
          "c0":"foo",
          "c1":22,
          "c2":"xx"
        }
      },
      ...
    ]
  }

422: Unprocessable Entity

Something went wrong with the request.

{ "error": <Error message> }

Query Specification

NiQL is modelled after standard SQL, but only supports read-only SELECT statements. A traditional query must at minimum have a SELECT and FROM clause in order to execute. While the SELECT clause can be anything, the FROM clause must specify a data set and version to query.

curl -i \
-H "Content-Type: application/json" \ 
-H "X-API-Key: {YOUR_API_KEY}" \ 
-X POST \ 
-d '{"query": "SELECT * FROM 2a6412c0-b3c9-420e-9487-abd21b664ac1/en-1 AS BramptonHomes"}' \ 
https://api.namara.io/v0/query.json

For example, if we were looking to query a data set with an id of 2a6412c0-b3c9-420e-9487-abd21b664ac1 and the version en-1, our minimum query would look like the example in the code column.

The parser will verify the table name and handle queries that reference it, but using aliases and quotes whenever possible is recommended.

Below is a summary of supported features:

SELECT Features

COUNT

  SELECT COUNT(*)
  FROM "data-set-id/en-0"

  SELECT COUNT(column1)
  FROM "data-set-id/en-0"

DISTINCT

  SELECT DISTINCT column1, column2
  FROM "data-set-id/en-0"

COUNT DISTINCT

  SELECT COUNT(DISTINCT column1)
  FROM "data-set-id/en-0"

MIN AND MAX

  SELECT MIN(column1) AS minColumn1, MAX(column2) AS maxColumn2
  FROM "data-set-id/en-0"

AVG AND SUM

  SELECT AVG(column1) AS avgColumn1, SUM(column1) AS sumColumn1
  FROM "data-set-id/en-0"

FROM Features

JOINS

  SELECT DataSet1.id, DataSet1.city, DataSet2.country
  FROM "data-set-id/en-0" AS DataSet1 INNER JOIN "data-set-id2/en-1" AS DataSet2
  ON DataSet1.foreign_id = DataSet2.external_id


Supports:

UNIONS

  SELECT id
  FROM "data-set-id/en-0"
  UNION
  SELECT objectid
  FROM "data-set-id2/en-1"

WHERE Features

Conditions

  SELECT id, address, city, province, country
  FROM "data-set-id/en-0"
  WHERE (country = 'Canada' AND province = 'Manitoba' AND NOT city = 'Winnipeg') OR country ='Mexico'

LIKE

  SELECT *
  FROM "data-set-id/en-0"
  WHERE country LIKE 'C_%'

ORDER BY

  SELECT *
  FROM "data-set-id/en-0"
  ORDER BY country, province, ... [ASC|DESC]

IN

  SELECT *
  FROM "data-set-id/en-0"
  WHERE country IN ('Mexico', 'Canada', ...)

BETWEEN

  SELECT *
  FROM "data-set-id/en-0"
  WHERE liquidation_date BETWEEN 2016-01-01 AND 2018-01-01

GROUP BY and HAVING

  SELECT COUNT(customer_id), country
  FROM "data-set-id/en-0"
  GROUP BY country
  HAVING COUNT(customer_id) > 100 

Subselects

  SELECT *
  FROM "data-set-id/en-0"
  WHERE total_count = [ANY|ALL] (SELECT COUNT(customer_id) FROM "data-set-id2/en-1")
  SELECT *
  FROM (SELECT customer_id, parent_account_id, purchase_total FROM "data-set-id2/en-1")
  AS subSelect
  WHERE purchase_total > 1500

Geospatial Features

Geometry properties for data sets are stored as GeoJSON, and will be rendered as that unless instructed otherwise. You can do this using the transformation functions ST_GeomFromText to create geometry objects, which can then be manipulated and transformed. Use ST_AsGeoJSON or ST_AsText in order to turn the final result back to text from binary.

Here's an example in which geometry_property is a property from the data set of type geometry (this information can be obtained in the API Info tab when viewing a data set):

  SELECT ST_AsGeoJSON(ST_GeomFromText(geometry_property))
  FROM "data-set-id/en-0"

Supported Functions

ST_AsGeoJSON
ST_AsJson
ST_AsText
ST_Buffer
ST_Contains
ST_Crosses
ST_Difference
ST_Disjoint
ST_Distance
ST_DWithin
ST_Envelope
ST_Equals
ST_GeomFromText
ST_GeomFromTextSrid
ST_Intersects
ST_Overlaps
ST_PointFunc
ST_Relate
ST_Touches
ST_Transform
ST_Union
ST_UnionAggregate
ST_Within
ST_XFunc
ST_XMax
ST_XMin
ST_YFunc
ST_YMax
ST_YMin

We are very interested in expanding the geospatial capabilities of NiQL. If there is additional functionality you need, or there are any issues with the the implementations, please do not hesitate to reach out to us.

Pagination with NiQL

Like the Data API, a maximum number of rows will be returned on each query. If the query string does not contain LIMIT X OFFSET Y, the parser will append the maximum number of allowable rows in order to enforce the limit.

For results larger than the allowed amount, manual pagination in subsequent requests will have to be used.

The default limit is 250 rows, but this may vary depending on which deployment of Namara you are interacting with. Refer to the Meta endpoint for instructions on how to obtain this information.

Get In Touch

We're easy to reach - visit our contact page, or talk directly to us while you use Namara by clicking the chat button in the bottom right. Please get in touch with us if you:

We would love to hear from you!