Deprecation Notice

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.

API Fundamentals

https://api.namara.io/v0/data_sets/{DATA_SET_ID}/data/{VERSION}?api_key={YOUR_API_KEY}&query_parameters={VALUE}

On the right is a basic template for a call made to our Data API. If it's confusing at first, don't worry - these docs are here to make sure you understand all the moving parts.

The API host is where we serve the data from. The data set and version can be found under the API tab in any data set, and are required for every API call.

Everything following the question mark (?) is a query parameter. Your API key is required to complete a call. Other parameters can be added using an ampersand (&) and give you the ability to filter and refine the results.

Query parameters change depending on the type of data set and the operation: basic parameters, geospatial parameters, exports, and aggregates each show a chart with the different operations.

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.

Data Set Versions

Our data is updated regularly and automatically, so values in rows and columns may change. The data set version is a snapshot of the data set's structure and properties. When that structure changes, we create a new version of the data set.

It is crucial that you include both the data set ID and the version in your queries. Both are found under the API tab for the data set.

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)

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)

Rate Limiting

Users are limited to 10,000 requests per month, as well as 100 data set downloads per month. When 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.

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 click "API Keys" to 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 click "API Keys" to 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 your user icon 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.

Data API

https://{NAMARA_API_HOST}/v0/data_sets/{DATA_SET_ID}/data

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 data set ID, version, and properties.

GET Data Query

https://api.namara.io/v0/data_sets/{DATA_SET_ID}/data

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

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?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?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?api_key={YOUR_API_KEY}&where=make IN ("CHEVROLET","CADILLAC")

2b) https://api.namara.io/v0/data_sets/057d7914-839e-4625-b8f8-2aa109f11e5a/data?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?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)

List all vehicles with CO₂ emissions less than 200g/km
a) Get fuel consumption ratings for all Cadillac and Chevrolet vehicles

b) The same operation with boolean operators
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)

Returns all rows in which the value in the specified column is within radius distance of the point specified by latitude and longitude.
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/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

Query Parameters	Type	Description
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 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>"
  }

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/aggregation

Parameter	Type	Description
data_set_id (required)	`string`	UUID for accessing the data set
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/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/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/aggregation?api_key={YOUR_API_KEY}&operation=count(*)&where=make="CADILLAC"

Reveals the average CO₂ emissions of Cadillac vehicles
Reveals the Cadillac vehicle with the least CO₂ emission
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 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, 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"

  SELECT COUNT(column1)
  FROM "data-set-id"

DISTINCT

  SELECT DISTINCT column1, column2
  FROM "data-set-id"

COUNT DISTINCT

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

MIN AND MAX

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

AVG AND SUM

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

FROM Features

JOINS

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

Supports:

INNER JOIN
RIGHT [OUTER] JOIN
LEFT [OUTER] JOIN
Implicit joins

UNIONS

  SELECT id
  FROM "data-set-id"
  UNION
  SELECT objectid
  FROM "data-set-id2"

WHERE Features

Conditions

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

LIKE

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

ORDER BY

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

IN

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

BETWEEN

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

GROUP BY and HAVING

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

Subselects

  SELECT *
  FROM "data-set-id"
  WHERE total_count = [ANY|ALL] (SELECT COUNT(customer_id) FROM "data-set-id2")

  SELECT *
  FROM (SELECT customer_id, parent_account_id, purchase_total FROM "data-set-id2")
  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"

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.

Advanced Features

Version Locking

We have created Version Locking in the event that it's important to maintain the properties from a previous version of the data set. Simply add /data/{VERSION} after the data set ID for the Data API, or /{VERSION} after the data set ID for the Query API.

For example, if we needed the first version of the data set with the ID 2a6412c0-b3c9-420e-9487-abd21b664ac1, our query to the Data API would read:

https://api.namara.io/v0/data_sets/2a6412c0-b3c9-420e-9487-abd21b664ac1/data/en-0

Or, for the Query API:

FROM "2a6412c0-b3c9-420e-9487-abd21b664ac1/en-0"

Making a query to https://api.namara.io/v0/data_sets/{DATA_SET_ID} will allow you to see all imported versions for the data set.

Get In Touch

We're easy to reach – visit our contact page and be in touch with us if you:

are experiencing any problems with the API;
would like to increase your request or download limit;
are looking for clarifications on the instructions;
notice any mistakes in our documentation; or
would like to send us any feedback.

We would love to hear from you!