Developers
All requests are sent POST with a required header, the body of the request is JSON.
Universal API Key suitable for all Surfy° products.
General
Main Endpoint
post
https://api.surfy.one/{product}/{method}[/{extras}]
Header parameters
Required
Email
String
Your E-mail
Required
Key
String
Your Free API key
Libraries
Python
ES6
CommonJS
Installation
pip install surfy
Initialisation
import Surfy from surfy
conf = {
'email': 'YOUR_EMAIL',
'key': 'YOUR_FREE_API_KEY'
}
surfy = Surfy(conf)
Installation
npm install surfy
Initialisation
import Surfy from 'surfy';
const conf = {
email: 'YOUR_EMAIL',
key: 'YOUR_FREE_API_KEY'
};
const surfy = new Surfy(conf);
Installation
npm install surfy
Initialisation
const Surfy = require('surfy');
const conf = {
email: 'YOUR_EMAIL',
key: 'YOUR_FREE_API_KEY'
};
const surfy = await Surfy(conf);
Get API Key
You will receive an email with a free API key at the specified address.
Vision
Surfy°Vision is a self-learning neural network for analysis and classification of images and video materials.
Image Recognition
Method description will be available soon.
Image Classification
Method description will be available soon.
Colours
Method description will be available soon.
Geo
Great Free Vector Maps and Rest API for work with GEO Data.
Geo IP
cURL
Python
Node.js
POST
https://api.surfy.one/geo/ip/{IP_ADDRESS}
If IP is not specified, it will be extracted from the API request.
Example
CURL -X POST -H "Email: {YOUR_EMAIL}" -H "Key: {YOUR_FREE_API_KEY}" https://api.surfy.one/geo/ip/{IP_ADDRESS}
Result
JSON {
ip: '2a01:e35:8bd9:8bb0:92b:8628:5ca5:5f2b',
code: 'FR',
country: 'France',
region: 'Ile-de-France',
city: 'Paris',
latitude: 48.858365,
longitude: 2.294532,
zip: '75000',
timezone: {
id: 'Europe/Paris',
name: 'Central European Standard Time',
gmt: 'GMT+01:00',
offset: 60,
localTime: '01/25/2023, 7:12:28 PM GMT+01:00'
},
status: true
}
Example
test_ips = ['8.8.8.8', '2a01:e35:8bd9:8bb0:92b:8628:5ca5:5f2b']
results = []
for ip in test_ips:
data = surfy.geo.ip(ip)
results.append(data)
print(results)
Results
[
{
ip: '8.8.8.8',
code: 'US',
country: 'United States of America',
region: 'California',
city: 'Mountain View',
latitude: 37.405992,
longitude: -122.078515,
zip: '94043',
timezone: {
id: 'America/Los_Angeles',
name: 'Pacific Daylight Time',
gmt: 'GMT-07:00',
offset: -420,
localTime: '01/25/2023, 11:12:28 AM GMT-07:00'
},
status: True
},
{
ip: '2a01:e35:8bd9:8bb0:92b:8628:5ca5:5f2b',
code: 'FR',
country: 'France',
region: 'Ile-de-France',
city: 'Paris',
latitude: 48.858365,
longitude: 2.294532,
zip: '75000',
timezone: {
id: 'Europe/Paris',
name: 'Central European Standard Time',
gmt: 'GMT+01:00',
offset: 60,
localTime: '01/25/2023, 7:12:28 PM GMT+01:00'
},
status: True
}
]
Example
let testIPs = ['8.8.8.8', '2a01:e35:8bd9:8bb0:92b:8628:5ca5:5f2b'];
let results = [];
for(let ip of testIPs){
let data = await surfy.geo.ip(ip)
results.push(data);
}
console.log(results);
Results
[
{
ip: '8.8.8.8',
code: 'US',
country: 'United States of America',
region: 'California',
city: 'Mountain View',
latitude: 37.405992,
longitude: -122.078515,
zip: '94043',
timezone: {
id: 'America/Los_Angeles',
name: 'Pacific Daylight Time',
gmt: 'GMT-07:00',
offset: -420,
localTime: '01/25/2023, 11:12:28 AM GMT-07:00'
},
status: true
},
{
ip: '2a01:e35:8bd9:8bb0:92b:8628:5ca5:5f2b',
code: 'FR',
country: 'France',
region: 'Ile-de-France',
city: 'Paris',
latitude: 48.858365,
longitude: 2.294532,
zip: '75000',
timezone: {
id: 'Europe/Paris',
name: 'Central European Standard Time',
gmt: 'GMT+01:00',
offset: 60,
localTime: '01/25/2023, 7:12:28 PM GMT+01:00'
},
status: true
}
]
Reverse Geocoding
cURL
Python
Node.js
POST
https://api.surfy.one/geo/reverse?lat={LATITUDE}&lng={LONGITUDE}
Example
CURL -X POST -H "Email: {YOUR_EMAIL}" -H "Key: {YOUR_FREE_API_KEY}" \
https://api.surfy.one/geo/reverse?lat={LATITUDE}&lng={LONGITUDE}
Result
JSON {
"status": true,
"coords": {
"latitude": 51.505856,
"longitude": -0.024096
},
"address": {
"office": "Credit Suisse",
"houseNumber": "1",
"road": "Cabot Square",
"quarter": "Canary Wharf",
"suburb": "Isle of Dogs",
"borough": "London Borough of Tower Hamlets",
"city": "London",
"stateDistrict": "Greater London",
"state": "England",
"postcode": "E14 4QJ",
"country": "United Kingdom",
"countryCode": "gb"
},
"timezone": {
"id": "Europe/London",
"name": "Greenwich Mean Time",
"gmt": "GMT",
"offset": 0,
"localTime": "11/14/2022, 12:42:36 PM GMT"
}
}
Example
coords = {
'lat': 51.505856,
'lng': -0.024096
}
result = surfy.geo.reverse(coords)
print(result)
Result
JSON {
"status": True,
"coords": {
"latitude": 51.505856,
"longitude": -0.024096
},
"address": {
"office": "Credit Suisse",
"houseNumber": "1",
"road": "Cabot Square",
"quarter": "Canary Wharf",
"suburb": "Isle of Dogs",
"borough": "London Borough of Tower Hamlets",
"city": "London",
"stateDistrict": "Greater London",
"state": "England",
"postcode": "E14 4QJ",
"country": "United Kingdom",
"countryCode": "gb"
},
"timezone": {
"id": "Europe/London",
"name": "Greenwich Mean Time",
"gmt": "GMT",
"offset": 0,
"localTime": "11/14/2022, 12:42:36 PM GMT"
}
}
Example
const coords = {
lat: 51.505856,
lng: -0.024096
};
let result = await surfy.geo.reverse(coords);
console.log(result);
Result
{
"status": true,
"coords": {
"latitude": 51.505856,
"longitude": -0.024096
},
"address": {
"office": "Credit Suisse",
"houseNumber": "1",
"road": "Cabot Square",
"quarter": "Canary Wharf",
"suburb": "Isle of Dogs",
"borough": "London Borough of Tower Hamlets",
"city": "London",
"stateDistrict": "Greater London",
"state": "England",
"postcode": "E14 4QJ",
"country": "United Kingdom",
"countryCode": "gb"
},
"timezone": {
"id": "Europe/London",
"name": "Greenwich Mean Time",
"gmt": "GMT",
"offset": 0,
"localTime": "11/14/2022, 12:42:36 PM GMT"
}
}
Timezone
cURL
Python
Node.JS
POST
https://api.surfy.one/geo/timezone?lat={LATITUDE}&lng={LONGITUDE}
Example
CURL -X POST -H "Email: {YOUR_EMAIL}" -H "Key: {YOUR_FREE_API_KEY}" \
https://api.surfy.one/geo/timezone?lat=46.524465&lng=6.623966
Result
JSON {
"status": true,
"latitude": 46.524465,
"longitude": 6.623966,
"id": "Europe/Zurich",
"name": "Central European Standard Time",
"gmt": "GMT+01:00",
"offset": 60,
"localTime": "11/15/2022, 11:57:42 AM GMT+01:00"
}
Example
options = {
'lat': 46.524465,
'lng': 6.623966
}
result = surfy.geo.timezone(options)
print(result)
Result
{
'status': True,
'latitude': 46.524465,
'longitude': 6.623966,
'id': 'Europe/Zurich',
'name': 'Central European Standard Time',
'gmt': 'GMT+01:00',
'offset': 60,
'localTime': '11/15/2022, 11:57:42 AM GMT+01:00'
}
Example
const options = {
lat: 46.524465,
lng: 6.623966
};
let result = await surfy.geo.timezone(options);
console.log(result);
Result
{
status: true,
latitude: 46.524465,
longitude: 6.623966,
id: 'Europe/Zurich',
name: 'Central European Standard Time',
gmt: 'GMT+01:00',
offset: 60,
localTime: '11/15/2022, 11:57:42 AM GMT+01:00'
}
Places
Method description will be available soon.
Words
Surfy Words is a text processing AI tool based on the principles of Natural Language Processing.
Language Translations
Translate
cURL
Python
Node.JS
POST
https://api.surfy.one/words/translate
If Source Language is not specified, it will be determined from the Source Text.
Example
CURL -X POST -H "Email: {YOUR_EMAIL}" -H "Key: {YOUR_FREE_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{ "source": { "lang": "en", "text": "Hello Surfy!" }, "target": { "lang": "fr" } }' \
https://api.surfy.one/words/translate
Result
JSON {
"status": true,
"source": {
"lang": "en",
"text": "Hello Surfy!"
},
"target": {
"lang": "fr",
"text": "Bonjour Surfy!"
}
}
Example
options = {
'source': {
'lang': 'en',
'text': 'Hello Surfy!'
},
'target': {
'lang': 'fr'
}
}
result = surfy.words.translations.translate(options)
print(result)
Result
{
"status": True,
"source": {
"lang": "en",
"text": "Hello Surfy!"
},
"target": {
"lang": "fr",
"text": "Bonjour Surfy!"
}
}
Example
const options = {
source: {
'lang': 'en',
'text': 'Hello Surfy!'
},
target: {
'lang': 'fr'
}
};
let result = await surfy.words.translations.translate(options);
console.log(result);
Result
{
status: true,
source: {
lang: 'en',
text: 'Hello Surfy!'
},
target: {
lang: 'fr',
text: 'Bonjour Surfy!'
}
}
List of Languages
cURL
Python
Node.JS
POST
https://api.surfy.one/words/translate/languages
Example
CURL -X POST -H "Email: {YOUR_EMAIL}" -H "Key: {YOUR_FREE_API_KEY}" \
https://api.surfy.one/words/translate/languages
Result
JSON {
"status": true,
"items": [
"en-es",
"en-fr",
"en-it",
"en-ru",
"en-uk",
...
"es-en",
"es-fr",
"es-it",
"es-ru",
"es-uk"
]
}
Example
result = surfy.words.translations.list()
print(result)
Result
{
'status': True,
'items': [
'en-es',
'en-fr',
'en-it',
'en-ru',
'en-uk',
...
'es-en',
'es-fr',
'es-it',
'es-ru',
'es-uk'
]
}
Example
let result = await surfy.words.translations.list()
console.log(result)
Result
{
status: true,
items: [
'en-es',
'en-fr',
'en-it',
'en-ru',
'en-uk',
...
'es-en',
'es-fr',
'es-it',
'es-ru',
'es-uk'
]
}
Language Detection
cURL
Python
Node.js
POST
https://api.surfy.one/words/define
Example
CURL -X POST -H "Email: {YOUR_EMAIL}" -H "Key: {YOUR_FREE_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{ "text": "Hello Surfy! What\'s new? Ciao Surfy! Cosa c'è di nuovo? ¿Qué hay de nuevo?" }' \
https://api.surfy.one/words/define
Result
JSON {
"status": true,
"langs": [
{
"en": 0.57
},
{
"it": 0.30
},
{
"es": 0.05
}
]
}
Example
corpus = "Hello Surfy! What's new? Ciao Surfy! Cosa c'è di nuovo? ¿Qué hay de nuevo?"
result = surfy.words.define(corpus)
print(result)
Result
{
'status': True,
'langs': [
{
'en': 0.57
},
{
'it': 0.30
},
{
'es': 0.05
}
]
}
Example
const corpus = "Hello Surfy! What's new? Ciao Surfy! Cosa c'è di nuovo? ¿Qué hay de nuevo?";
let result = await surfy.words.define(corpus);
console.log(result);
Result
{
'status': true,
'langs': [
{
'en': 0.57
},
{
'it': 0.30
},
{
'es': 0.05
}
]
}
Tone of Voice
cURL
Python
Node.js
POST
https://api.surfy.one/words/tone
Example
CURL -X POST -H "Email: {YOUR_EMAIL}" -H "Key: {YOUR_FREE_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{ "text": "My dear friend! I am very happy about your letter. How long has it been since we\'ve seen each other, maybe it\'s time we met?" }' \
https://api.surfy.one/words/tone
Result
JSON {
"status": true,
"positive": 0.75,
"pressure": 0.32,
"politeness": 0.88
}
Example
corpus = "My dear friend! I am very happy about your letter. How long has it been since we've seen each other, maybe it's time we met?"
result = surfy.words.tone(corpus)
print(result)
Result
{
'status': True,
'positive': 0.75,
'pressure': 0.32,
'politeness': 0.88
}
Example
const corpus = "My dear friend! I am very happy about your letter. How long has it been since we've seen each other, maybe it's time we met?";
let result = await surfy.words.tone(corpus);
console.log(result);
Result
{
status: true,
positive: 0.75,
pressure: 0.32,
politeness: 0.88
}
Summarisation
Method description will be available soon.
Enterprise &
Custom Solutions
All Surfy° Ecosystem solutions are customizable to meet your specific business objectives.
For any questions related to custom deployment of Surfy° Ecosystem for your Enterprise, please contact us.