API Reference

API Domain.

https://api.jamnav.com/

The JAMNAV API is a RESTful web service that provides developers with read only access to geographical data in the JAMNAV database. The data is organised into resources accessible by sending requests to the API's resource endpoints.

There are two(2) main requirements for successful interaction with the API. Firstly, developers should ensure their requests are sent via a secure connection (HTTPS). Secondly, each request to the API requires authentication. Unauthenticated requests or requests sent via HTTP are rejected by the API and will result in a API error.

By utilizing or interacting directly or indirectly with the JAMNAV API, you have agreed to the JAMNAV terms of service.

Version

Root Version URL

https://api.jamnav.com/v1/

Example Response

{
    "divisions": "https://api.jamnav.com/v1/divisions/",
    "settlements": "https://api.jamnav.com/v1/settlements/",
}

The current release of the API available to developers is version 1.0. This version contains searching/filtering functionality as well as resources specific to Jamaica such as Jamaican parishes, settlements and points of interest.

Resources in this version can be accessed by adding the version identifier v1 to the base url. The version endpoint lists the resource endpoints in the API and can be used as a directory.

Authentication

# Unauthenticated request.
curl "https://api.jamnav.com/v1/"

# Authenticated request
curl "https://api.jamnav.com/v1/" 
    -H "Authorization: Token <api_token>"

Unauthenticated response

{ "detail" : "Authentication credentials were not provided." }

Invalid token response

{ "detail": "Invalid token." }

The API authenticates requests using a secret key or token. This key is only generated after the authorisation of a developer account. After authorisation, the developer will be able to view their key by logging into the site and navigating to the JAMNAV Developer Dashboard. The developer's API key will be prominently displayed in the dashboard's user interface.

The API key should be included in every request to the API through the addition of a Authorization HTTP header. The value of the Authorization header should be the secret API key prefixed with the string literal Token. If a request does not have an Authorization header or the API token in the header is invalid the API will respond with a 401 status accompanied by an error message describing the issue.

Formats

Example GeoJSON.

{
    "type": "FeatureCollection",
    "features": [
        {
            "id": 1
            "type": "Feature",
            "geometry": {
                "point": {
                    "type": "Point",
                    "coordinates": [-123.0208, 44.0464],
                }
            },
            "properties": {
                "name": "Mona Informatix Ltd",
            }
        }
    ]
}

JSON

Responses from the JAMNAV API are all valid JSON including the index or version endpoint, resource endpoints and API functions such as nearby points of interest.

GeoJson

The JAMNAV API returns geographic data as valid GeoJSON, a specialized form of the JSON format. As per the GeoJSON specification the API details geographic resources as a type of Feature with an id, properties and a geometry(point, polygon, line, multipolygon). The API also lists these resources as a FeatureCollection with a array of Features and pagination properties.

Pagination

Example Pagination

https://api.jamnav.com/v1/<resource>/?page_size=10

Paginated Response

{
    "type": "FeatureCollection",
    "count": 300,
    "next": "https://api.jamnav.com/v1/locations/?page=2",
    "previous": null,
    "features": [
        {
            "id": 1
            "type": "Feature",
            "geometry": {
                "point": {
                    "type": "Point",
                    "coordinates": [-123.0208, 44.0464],
                }
            },
            "properties": {
                "name": "Mona Informatix Ltd",
            }
        },
        ...

}

All responses from list endpoints are automatically paginated using page number pagination. This allows developers to access a subset of a resource by specifying the page number.

The maximum pagination size is 500. By default the resource page size is 100.

Custom Pagination

The API's default pagination scheme can be customized by specifying the page_size in the request query string. The following query variables can be used to update the API's pagination.

Variable
page_size	The amount of the resource to be listed in each page.
page	The number of the page requested.

Paginated Response

Pagination adds some special keys to the API resource response to help with client-side pagination. These are:

Properties
count	The total number of the resouce available.
next	The url of the next page of the resource.
previous	The url the previous page of the resource.

Resources

API Resource URL Format

# List Resource
https://api.jamnav.com/v1/<resource_name>/

# Resource Detail
https://api.jamnav.com/v1/<resource_name>/<recource_id>/

The JAMNAV API currently has three (3) resources for geographical data in Jamaica. These are:

Parishes
Settlements
Points Of Interest

Each resource has a list and a detail endpoint that can be accessed by appending the resource name and the resource instance indentifier. The resource list endpoints have search functionality based on the properties of the resource.

Parishes

JAMNAV API Parish Endpoint

# List Parishes
https://api.jamnav.com/v1/parishes/

# Search Parishes
https://api.jamnav.com/v1/parishes/?name=Clarendon

# Parish Detail
https://api.jamnav.com/v1/parishes/1/

API Response

{
    "id": 14,
    "type": "Feature",
    "geometry": {
    "type": "MultiPolygon",
    "coordinates": [
        [
            [
                [
                    -77.8750165889251,
                    18.23890418226235
                ],
                [
                    -77.87485932323689,
                    18.23863991521881
                ],
                ...
            ]
            ...
        ]
    ],
    "properties": {
        "name": "Westmoreland",
        "data": {
            "perimeter": 166476.942,
            "pop_199": 46770,
            "total_area": 785194118.784,
            "area": 785189957.721,
            "count": 14,
            "acres": 194019.319,
            "area_km": 785.189957721,
            "pop_200": 55568
            }
        }
    }
}

The JAMNAV API Parishes are accurate Multipolygon geometries with the following properties and data:

Properties
name	The name of the parish.
perimeter	The parish's perimeter in kilometers.
pop_1991	The parish's population in 1991.
pop_2001	The parish's population in 2001.
pop_2011	The parish's population in 2011.
acres	The acres of land in the parish.
area_km	The parish's area in kilometers.
area_m	The parish's area in meters.

Parishes can be filtered by their names.

Settlements

JAMNAV API Settlement Endpoint

# List Settlements
https://api.jamnav.com/v1/settlements/

# Search Settlements
https://api.jamnav.com/v1/settlements/?name=Friendship

# Settlement Detail
https://api.jamnav.com/v1/settlements/1/

API Response

{
    "id": 103,
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            -78.23197477894558,
            18.39285490914639
        ]
    },
    "properties": {
        "name": "Friendship",
        "parish": {
            "id": 2,
            "name": "Hanover"
        }
    }
}

The JAMNAV API Parishes are point geometries with the following properties:

Properties
name	The name of the settlement.
parish	The parish the settlement is located in.

Search Settlements

Settlements have two (2) field filters. These are:

name
parish

Road Segments

JAMNAV API Road Segment Endpoint

# List Road Segments
https://api.jamnav.com/v1/roadsegments/

# Search Road Segments
https://api.jamnav.com/v1/roadsegments/?name=pinewood+dr

# Road Segment Detail
https://api.jamnav.com/v1/roadsegments/1/

API Response

{
    "type": "Feature",
    "geometry": {
        "type": "LineString",
        "coordinates": [
            [
                -76.85018,
                18.04095
            ],
            [
                -76.84943,
                18.04092
            ]
        ]
    },
    "properties": {
        "grmn_type": "RESIDENTIAL",
        "name": "pinewood dr",
        "route_lvl": 1.0,
        "speed_limit": 50,
        "speed_format": 1,
        "one_way": 0,
        "toll_road": 0,
        "link_id": 10179,
        "sett_name": "Duhaney Park",
        "sett_w_pari": "Duhaney Park, St. Andrew",
        "parish_set": "St. Andrew",
        "comm_name": "FOREST HILLS/PLANTATION HEIGHTS",
        "poi_name": "Casa Roma Decima",
        "poi_address": "Belvedere Rd, Forest Hills/Plantation Heights",
        "poi_parish": "St. Andrew"
    }
},

The JAMNAV API Road Segments are point geometries with the following properties:

Properties
grmn_type	Road Segment Type (category) based on function. For example.... Residential, Driveway or Major Highway.
name	Name of Road Segment with suffix eg. Rd, Ave, Cl etc. Road Segments without a name or names we do not have are named as "road.
route_lvl	Relate directly to GRMN_TYPE and gives the road segment class based on the Garmin classification used. It is a road segment classification scheme that has adapted to the Jamaican situation well.
speed_limit	The official speed limit of the road. All public road in the KMA are 50km/hr or less. Except for Highway 2000 etc.
speed_format	1 indicates that we are using Metric and not Statute.
one_way	0 means 2 way navigation possible on that line while 1 means that navigation is possible in only 1 direction.
toll_road	0 mean it is not a toll road (free travel), while 1 means yes it is a toll road.
link_id	Unique number given to each road segment number. This should not repeat itself in this shapefile or in any other shapefile to be used as a part of a map build..
sett_name	The nearest settlement to respective road segment.
sett_w_pari	The nearest settlement with parish in the same field (may not be useful to u).
parish_set	Just the parish the nearest settlement corresponding to the road segment falls in.
comm_name	The nearest community to respective road segment.
poi_name	The nearest point of interest to respective road segment.
poi_address	Address of nearest point of interest to respective road segment**.
poi_parish	Parish in which the closest POI to respective road segment falls.

Search Road Segments

Road Segments have field filters:

grmn_type
name
route_lvl
speed_limit
speed_format
one_way
toll_road
one_way
toll_road
link_id
sett_name
sett_w_pari
parish_set
comm_name
poi_name
poi_address
poi_parish

Roads

JAMNAV API Road Endpoint

# List Roads
https://api.jamnav.com/v1/roads/

# Search Roads
https://api.jamnav.com/v1/roads/?name=bank+ave

# Road Detail
https://api.jamnav.com/v1/roads/1/

API Response

{
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            -76.7667650426269,
            17.97228000016935
        ]
    },
    "properties": {
        "name": "bank ave",
        "parish": {
            "id": 17,
            "name": "Kingston"
        }
    }
},

The JAMNAV API Roads are point geometries with the following properties:

Properties
name	Name of Road with suffix eg. Rd, Ave, Cl etc. Roads without a name or names we do not have are named as "road.
parish	The parish the road is located in.
country	The country the road is located in.

Search Roads

Roads have field filter:

name

Points Of Interest

Points Of Interest API Endpoints

# List Points Of Interest
https://api.jamnav.com/v1/locations/

# Search Points Of Interest
https://api.jamnav.com/v1/locations/?name=Tastee+Portmore

# Point Of Interest Detail
https://api.jamnav.com/v1/locations/1/

# Nearby Points Of Interest
https://api.jamnav.com/v1/locations/nearby/?lat=17.96962232000001&lng=-76.86816727

API Response

{
    "id": 25762,
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [
            -76.96756815850807,
            18.317445587762123
        ]
    },
    "properties": {
        "name": "Mile Gully Basic School",
        "categories": [],
        "phone_number": "",
        "address": "Central Rd, Lower Work"
        "parish": {
            "id": 11,
            "name": "St. Mary"
        }
    }
}

Resource Properties

JAMNAV API Points Of Interest have the following properties:

Properties
name	The name of the point of interest.
categories	The categories that the point of interest is classified by.
phone_number	The phone number of the point of interest.
address	The address of the point of interest.
parish	The parish that the point of interest is located in.

Search Points Of Interests

Points Of Interest have three (3) field filters. These are:

name
parish
categories

Nearby Points Of Interest

The nearby points of interest endpoint adds functionality that allows points of interest to be ordered by their proximity to a point. The point should be specified in the request query string as lat and lng variables. Points of Interest can also be filtered by their name, parish, category as well as their proximity to the specified point on this endpoint.

API Reference

Version

Authentication

Formats

JSON

GeoJson

Pagination

Custom Pagination

Paginated Response

Resources

Parishes

Settlements

Search Settlements

Road Segments

Search Road Segments

Roads

Search Roads

Points Of Interest

Resource Properties

Search Points Of Interests

Nearby Points Of Interest

Categories