Getting started overview

GeoScore provides APIs for analyzing sentiment and context based on geographic location, enabling developers to integrate hyperlocal insights into their applications. This guide focuses on the foundational steps required to begin using GeoScore: account creation, API key management, and executing a successful initial request. GeoScore offers a free tier with 1000 API calls per month for initial development and testing.

The core of GeoScore's functionality revolves around its Location Sentiment API, Geo-Contextual NLP, and Social Media Analysis tools. These services are accessed via RESTful API endpoints, requiring an API key for authentication. The process described here will enable you to make your first authenticated call, typically to the Location Sentiment API, which is a primary offering of the platform.

To ensure a smooth onboarding experience, it is recommended to have a basic understanding of HTTP requests and JSON data structures. While GeoScore provides documentation with examples in Python, Node.js, and cURL, the underlying principles apply across various programming environments. Understanding how to send a POST request with a JSON body and handle the JSON response is key to working effectively with any REST API, as detailed in Mozilla's POST request documentation.

Quick reference table

Step What to do Where
1. Create Account Register for a new GeoScore account. GeoScore Signup Page
2. Get API Key Locate and copy your unique API key. GeoScore Dashboard > API Keys section
3. Make Request Send an authenticated POST request to an endpoint. Your preferred development environment (e.g., cURL, Python, Node.js)
4. Parse Response Process the JSON response from the API. Your application code

Create an account and get keys

Access to GeoScore's services requires an active account and a valid API key. This key authenticates your requests and associates them with your usage plan.

Account registration

  1. Navigate to the official GeoScore signup page.
  2. Provide the required information, typically including an email address and password.
  3. Complete any necessary email verification steps to activate your account.
  4. Once registered, you will be redirected to your GeoScore user dashboard.

API key retrieval

Upon successful account creation and login, your API key will be available in your dashboard:

  1. Log in to your GeoScore dashboard.
  2. Look for a section labeled "API Keys", "Credentials", or similar.
  3. Your API key will be displayed. It is a unique alphanumeric string.
  4. Copy this key securely. It acts as your authentication token for all API requests. Treat it like a password to prevent unauthorized access to your account and usage.

GeoScore's documentation emphasizes securing your API key and not embedding it directly into client-side code or public repositories. Best practices for API key management often involve using environment variables or a secure configuration management system, as outlined in general API security guidelines.

Your first request

With an API key in hand, you can now make your first call to GeoScore's API. This example demonstrates how to use the Location Sentiment API, a core GeoScore product, to analyze sentiment for a given location and text.

API Endpoint

The primary endpoint for Location Sentiment analysis is typically structured as:

POST https://api.geoscore.io/v1/sentiment/location

Refer to the GeoScore API reference for the Location Sentiment endpoint for the most up-to-date and complete details on required parameters and response structure.

Request Headers

All requests must include your API key in the Authorization header and specify the content type:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body (JSON)

The request body for the Location Sentiment API typically includes geographic coordinates (latitude and longitude) and the text to be analyzed:

{
  "latitude": 34.0522,
  "longitude": -118.2437,
  "text": "This coffee shop has a fantastic vibe and great service!"
}

Example using cURL

cURL is a command-line tool for making HTTP requests and is useful for quick testing:

curl -X POST \
  https://api.geoscore.io/v1/sentiment/location \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "latitude": 34.0522, "longitude": -118.2437, "text": "This coffee shop has a fantastic vibe and great service!" }'

Replace YOUR_API_KEY with the actual key copied from your GeoScore dashboard.

Example using Python

Using the requests library in Python:

import requests
import os

API_KEY = os.getenv("GEOSCORE_API_KEY") # Recommended: use environment variables
API_ENDPOINT = "https://api.geoscore.io/v1/sentiment/location"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

data = {
    "latitude": 34.0522,
    "longitude": -118.2437,
    "text": "This coffee shop has a fantastic vibe and great service!"
}

try:
    response = requests.post(API_ENDPOINT, headers=headers, json=data)
    response.raise_for_status() # Raise an exception for HTTP errors
    print(response.json())
except requests.exceptions.HTTPError as err:
    print(f"HTTP error occurred: {err}")
except Exception as err:
    print(f"Other error occurred: {err}")

Ensure you have the requests library installed (pip install requests). For security, load your API key from an environment variable (e.g., GEOSCORE_API_KEY) rather than hardcoding it.

Expected Response

A successful response will typically return a JSON object containing the sentiment analysis results:

{
  "sentiment": {
    "overall": "positive",
    "score": 0.85,
    "magnitude": 0.9
  },
  "geo_context": {
    "country": "USA",
    "city": "Los Angeles",
    "timezone": "America/Los_Angeles"
  },
  "text_analysis": {
    "word_count": 10,
    "language": "en"
  }
}

The exact structure may vary based on the specific GeoScore API endpoint called and the parameters provided. Consult the GeoScore API reference for precise response schemas.

Common next steps

After successfully making your first GeoScore API call, consider these next steps to further integrate and optimize your usage:

  • Explore other endpoints: Review the GeoScore API reference to understand other available services, such as Geo-Contextual NLP or Social Media Analysis, and how they can enhance your application.
  • Integrate into your application: Move beyond simple test scripts and integrate the API calls into your production-ready application code. Implement robust error handling and logging.
  • Monitor usage: Keep track of your API call usage through your GeoScore dashboard to stay within your plan limits or to anticipate when an upgrade might be necessary.
  • Implement caching: For frequently requested but slowly changing data, implement caching strategies to reduce the number of API calls and improve performance.
  • Review pricing: Familiarize yourself with GeoScore's pricing plans to understand the costs associated with increased usage and to choose a plan that aligns with your application's needs.
  • Explore advanced features: Investigate any advanced features or parameters available for each endpoint to fine-tune the analysis results or retrieve more specific data.
  • Set up webhooks (if available): If GeoScore offers webhook functionality for asynchronous updates or event notifications, consider setting them up to react to real-time data or processing completion.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and their solutions:

  • 401 Unauthorized: This usually means your API key is missing, incorrect, or expired. Double-check that you've included the Authorization: Bearer YOUR_API_KEY header correctly and that the key itself is accurate. Ensure there are no leading or trailing spaces.
  • 400 Bad Request: This indicates an issue with your request body or parameters. Verify that your JSON payload is correctly formatted and includes all required fields as per the GeoScore API documentation. Check for typos in parameter names or incorrect data types.
  • 403 Forbidden: Your account might not have the necessary permissions for the requested endpoint, or your API key might be restricted. Check your GeoScore dashboard for any account status messages or limitations on your API key.
  • 5xx Server Error: These errors (e.g., 500 Internal Server Error) indicate an issue on GeoScore's side. While less common, if you encounter these, it's best to check the GeoScore status page (if available) or contact GeoScore support.
  • Network issues: Ensure your development environment has a stable internet connection and no firewall rules are blocking outgoing HTTP requests to api.geoscore.io.
  • Incorrect endpoint: Confirm that the URL you are sending the request to matches the correct API endpoint specified in the GeoScore API reference, including the correct version (e.g., /v1/).
  • Environment variable not loading: If using environment variables for your API key, ensure they are correctly set and accessible by your script. For example, in Python, os.getenv("GEOSCORE_API_KEY") will return None if the variable isn't set.

When troubleshooting, use tools like your browser's developer console (for client-side requests), cURL, or Postman to inspect the exact request being sent and the response received. This can help pinpoint discrepancies quickly.