cURL C# Go Java Javascript PHP Python Ruby Swift

Introduction

Welcome to the Objectia API.

Official libraries for the Objectia API are available in several languages.

Endpoints

All API requests are made to api.objectia.com and all requests are served over HTTPS. Calls made over plain HTTP will fail.

The current API version is v1.

API Endpoint

https://api.objectia.com/v1

Versioning

As we develop future versions of our API that are not backwards-compatible, we will leave the old version running and create a new url for the latest version. We will retain support for obsolete versions for a generous period of time and will send email notifications of any changes.

Future versions will be v2, v3, etc.

Authentication

All requests to the API must be authenticated with an access token. You can submit the access token in the HTTP request header, or you can specify the access token as a HTTP URL query parameter.

In the HTTP Authorization header:

Authorization: "Bearer d699e37f506f49f1aa15105228833cd7"

In the URL as the access_token parameter:

https://api.objectia.com/v1/geoip/8.8.8.8?api_key=d699e37f506f49f1aa15105228833cd7

API requests without authentication will fail.

Rate limits

API access rate limits are applied at a per-key basis in unit time. Access to the API using a key is limited to 60 requests per minute. In addition, every API response is accompanied by the following set of headers to identify the status of your consumption.

Header Description
X‑RateLimit‑Limit The maximum number of requests that the consumer is permitted to make per minute.
X‑RateLimit‑Remaining The number of requests remaining in the current rate limit window.
X‑RateLimit‑Reset The time at which the current rate limit window resets in UTC epoch seconds.

Once you hit the rate limit, you will receive a response similar to the following JSON, with a status code of 429 Too Many Requests.

{
  "status": 429,
  "success": false,
  "message": "Rate Limit exceeded"
}

Errors

Objectia uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2XX range indicate success. Codes in the 4XX range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5XX range indicate an error with Objectia’s servers (these are rare).

Making requests

The API only supports JSON at present.

The Content-Type header:

Content-Type: "application/json"

You must supply a Content-Type: application/json header in PUT and POST requests. You must set an Accept: application/json header on all requests.

Responses

Single-item responses will be in this format:

{
  "status": 200,
  "success": true,
  "data": {
    "id": 1,
    "some": "more data ..."
  }
}

Most endpoints return a single model of data.

Multi-item responses will be in this format:

{
  "status": 200,
  "success": true,
  "data": [
    { 
      "id": 1,
      "some": "more data ..."
    },
    { 
      "id": 2,
      "some": "more data ..."
    }
  ]
}

Your use and access to the API is expressly conditioned on your compliance with the policies, restrictions, and other provisions related to the API set forth in our API License Agreement and the Privacy Policy, in all uses of the API. If Objectia believes that you have or attempted to violate any term, condition, or the spirit of these policies or agreements, your right to access and use the API may be temporarily or permanently revoked.

Getting Started

In this section we will …

Resources

API basics tutorials

API clients

Geo IP API

The Geo IP API ….

GET Location by IP

https://api.objectia.com/v1/geoip/:ip

Retrieves the geographical location for a given IP address or domain name.

Get IP Location

Example request:

curl https://api.objectia.com/v1/geoip/8.8.8.8 \
  -H "Authorization: Bearer YOUR-API-KEY" \
  -H "Accept: application/json"
package main

import (
  "fmt"
  objectia "github.com/objectia/objectia-go"
)

func main() {
  apiKey := "YOUR-API-KEY"
  client, err := api.NewClient(apiKey, nil)
  if err != nil {
    panic(err)
  }
  result, err := client.GetIPLocation("8.8.8.8")
  if err != nil {
    panic(err)
  }
  fmt.Printf("Location: %+v\n", result)
}

Example response:

{
  "data": {
    "ip": "8.8.8.8",
    "type": "ipv4",
    "continent_name": "North America",
    "continent_code": "NA",
    "country_name": "United States",
    "country_name_native": "United States",
    "country_code": "US",
    "country_code3": "USA",
    "capital": "Washington D.C.",
    "region_name": "California",
    "region_code": "CA",
    "city": "Mountain View",
    "postcode": "94043",
    "latitude": 37.405992,
    "longitude": -122.078515,
    "phone_prefix": "+1",
    "currencies": [
      {
        "code": "USD",
        "num_code": "840",
        "name": "US Dollar",
        "name_plural": "US dollars",
        "symbol": "$",
        "symbol_native": "$",
        "decimal_digits": 2
      }
    ],
    "languages": [
      {
        "code": "eng",
        "code2": "en",
        "name": "English",
        "native_name": "English",
        "rtl": false
      }
    ],
    "flag": "https://cdn.objectia.com/assets/flags/us.svg",
    "flag_emoji": "🇺🇸",
    "is_eu": false,
    "internet_tld": ".us",
    "timezone": {
      "id": "America/Los_Angeles",
      "localtime": "2019-02-19T08:56:28-08:00",
      "gmt_offset": -28800,
      "code": "PST",
      "daylight_saving": true
    }
  },
  "privacy": "https://objectia.com/privacy",
  "status": 200,
  "success": true,
  "terms": "https://objectia.com/terms"
}
Parameter Value
ip
The IP address or domain name to look up.