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
orhttps://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 CO2 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 bylatitude
andlongitude
.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 CO2 emissions of Cadillac vehicles
Reveals the Cadillac vehicle with the least CO2 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!