API Overview

Web API

NetToolKit provides a RESTful JSON web API, tile server, and hosted JavaScript files. All API resources are served from host api.nettoolkit.com.
Sample request
curl "https://api.nettoolkit.com/v1/geo/geocodes?address=790+E+Duane+Ave,+Sunnyvale,+CA+94085" \
-H "X-NTK-KEY: $YOUR_KEY_HERE"

Authentication

API requests are authenticated using an API key. Requests without a valid API key will generally be rejected.

API keys can be passed in as a header or embedded directly into the query string.

Sample API key in header
curl "https://api.nettoolkit.com/v1/resources" \
-H "X-NTK-KEY: $YOUR_KEY_HERE"
Sample API key in query string
curl "https://api.nettoolkit.com/v1/resources?key=$YOUR_KEY_HERE"

You can view your API keys on your account home page, or get a free key for testing. Test keys are good for 1000 requests per day.

Response

The web API returns RESTful responses, including a standard HTTP status code and the requested resource or an error. If an error occurs, you can expect to receive a more detailed error code and a message as part of the response.

JSON Packet

JSON responses will always have a standard format called a JSON packet.

Sample JSON packet format
{
    "code": 1000,
    "message": "Something or another",
    "results": []
}

JSON packet attributes

KeyTypeDescription
codenumberNumeric status code; see full list above
messagestring(Optional) More detailed explanation
queryobject(Optional) Query as understood by the server
resultsarrayList of results for successful requests
Sample success packet
{
    "code": 1000,
    "query": {
        "address_query": "790 E Duane Ave, Sunnyvale, CA 94085"
    },
    "results": [
        {
            "address": "790 Duane Av E, Sunnyvale, CA, 94085",
            "latitude": 37.3865321,
            "longitude": -122.01121455,
            "house_number": "790",
            "street_name": "Duane",
            "street_type": "Av",
            "city": "Sunnyvale",
            "state": "California",
            "state_code": "CA",
            "postal_code": "94085",
            "precision": "rooftop",
            "provider": "Openaddresses",
            "provider_geocode_time": "133",
            "ntk_geocode_time": "192"
        }
    ]
}
Sample error packet
{
    "code": 7002,
    "message": "Missing parameter: address",
    "results": []
}

Status codes

CodeValueHTTP StatusDescription
1000OK200No problems here
1001UNDERSTOOD200Request understood, but no content returned
2000INTERNAL_ERROR500Something has gone wrong on our end
2001UNKNOWN_ERROR500Something we've never seen has gone wrong
2002CONNECTION_TIMEOUT408Connection to external service timed out
2003SERVICE_TIMEOUT408Connection to internal service timed out
2004GEOCODE_SERVER_BUSY503Geocoding server is unavailable
2005SERVICE_UNAVAILABLE503Service is temporarily unavailable
3000NOT_PERMITTED403Request not permitted
3001INSUFFICIENT_CREDITS400Not enough credits to complete request
3002INVALID_CREDENTIALS401Invalid key found
3003OVER_QUOTA403Too many requests!
3004ACCOUNT_DATABASE_REQUIRED403Resource requires account database (coming soon)
4000BAD_REQUEST400Invalid request
4001INVALID_PARAMETER400Invalid parameter for request found
4002MISSING_PARAMETER400Required parameter for request not found
5000NOT_FOUND404No results for request
5001RESOURCE_DEPENDENCY_ERROR409Something else depends on this resource
5002CONFLICT409Resource conflict found
5003RESOURCE_EXPIRED404Resource has expired
5500UNKNOWN_ROUTE404No matching route for request