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 -s -H "X-NTK-KEY: $your_key_here" \
"https://api.nettoolkit.com/v1/geo/geocodes?address=790+E+Duane+Ave,+Sunnyvale,+CA+94085"

Authentication

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

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

Sample API key in header
curl -s -H "X-NTK-KEY: $your_key_here" \
"https://api.nettoolkit.com/v1/resources"
Sample API key in query string
curl -s \
"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.

JSON Packet

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

Sample JSON packet format
{
  code: 1000,
  message: "Something or another",
  query: {},
  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'.",
  query: {
    address_query: "",
  },
  results: []
}

Different queries may include additional meta data in the packet. Check the documentation specific to your query for more details.

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.

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

JSON Packet

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

Sample JSON packet format
{
  code: 1000,
  message: "Something or another",
  query: {},
  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'.",
  query: {
    address_query: "",
  },
  results: []
}