Request AccessSupport

How to use the API

This section explains how to send API requests to the Enable's Geographic Place API.

The examples provided use the sandbox environment. For production use, be sure to replace the URL with the production endpoint.

Authentication

You must obtain a valid access token before making requests to the Geographic Place API. For details on generating an access token, refer to the Auth API documentation.

Place Details

Prerequisites

You must have access to a valid client ID and secret of an active application that has been granted the required geoPlaceAPI scopes (geoPlaceAPI.read) in Enables Identity and Access Management platform, Okta. 

  • If you are not sure how to generate an access token, start here.  
  • A valid FSL or TUI is required for get place by ID
import requests
import uuid

'''Step 1: Generate an access token via the Auth v2 API and ensure it has the following scopes
- geoPlaceAPI.read'''

token = 'your_access_token_here'  # Replace with your actual access token

''' Step 2: Set up the request parameters'''

x_transaction_id = str(uuid.uuid4())
place_id  = '30175287CESL009' # Replace with the FSL or TUI for the place you want to query

''' Step 3: Make the API request to retrieve place details '''
def request_place_details_from_api(access_token, place_id, x_transaction_id) -> dict:
    """Request place details from the Enable GeoPlace API.
    Args:
        access_token (str): The access token for authentication.
        place_id (str): The ID of the place to query.
        x_transaction_id (str): A unique transaction ID for the request.
    Returns:
        dict: The JSON response containing place details, or None if the request fails.
    """
    
    base_url = "https://staging.apis.enable.net.nz/geoPlaceAPI/v1/place/"
    headers = {
        "content-type": "application/json",
        "Authorization": f"Bearer {access_token}",
        "X-Transaction-ID": x_transaction_id,
    }
    url = f"{base_url}{place_id}"
    response = requests.get(url, headers=headers)
   
    if response.status_code == 200:
        print("place details retrieved successfully.")
        return response.json()
    else:
        print("There as an error retrieving place details")
        return {"Error": f"{response.status_code} - {response.text}"}
        
if __name__ == "__main__":
    place_details = request_place_details_from_api(token, place_id, x_transaction_id)
    print(place_details)  # Print the retrieved place detail

Place Search

Prerequisites

You must have access to a valid client ID and secret of an active application that has been granted the required geoPlaceAPI scopes in Enables Identity and Access Management platform, Okta. 

  • If you are not sure how to generate an access token, start here.
  • A valid search parameter as described in the API spec

Example Python:

import json
import requests
import uuid

'''
Step 1: Generate an access token via the Auth v2 API and ensure it has the following scopes
- geoPlaceAPI.read
'''

token = 'your_access_token_here'  # Replace with your actual access token

''' Step 2: Set up the request parameters'''

x_transaction_id = str(uuid.uuid4())
limit = 10  # Optional: Set the limit for the number of results returned
offset = 0  # Optional: Set the offset for pagination

place = '126 ST ASAPH STREET'# Example place, replace with your actual place

''' Step 3: Make the API request to retrieve place details '''
def post_place_search_endpoint(access_token, place, x_transaction_id) -> dict:
    """Post place search endpoint to the Enable GeoPlace API.
    Args:
        access_token (str): The access token for authentication.
        place (str): The place to query, formatted as per API requirements.
        x_transaction_id (str): A unique transaction ID for the request.
    Returns:
        dict: The JSON response containing place search results, or None if the request fails.
    """
    base_url = "https://staging.apis.enable.net.nz/geoPlaceAPI/v1/place/search"

    headers = {
        "content-type": "application/json",
        "Authorization": f"Bearer {access_token}",
        "X-Transaction-ID": x_transaction_id,
    }
    params = {
        "limit": limit,
        "offset": offset,
    }
    payload = {
        "name": place
    }

    response = requests.post(base_url, headers=headers, json=payload, params=params)

    if response.status_code == 200:
        print("place search results retrieved successfully.")
        return response.json()
    else:
        print("There was an error retrieving place search results")
        return {"Error": f"{response.status_code} - {response.text}"}

if __name__ == "__main__":
    place_search_results = post_place_search_endpoint(token, place, x_transaction_id)
    print(json.dumps(place_search_results))

 

Place Resource

Prerequisites

You must have access to a valid client ID and secret of an active application that has been granted the required geoPlaceAPI scopes in Enables Identity and Access Management platform, Okta. 

  • If you are not sure how to generate an access token, start here.
  • A valid place_id parameter as described in the API spec

Example Python:

import requests
import uuid

'''Step 1: Generate an access token via the Auth v2 API and ensure it has the following scopes
- geoPlaceAPI.read
'''

token = 'your_access_token_here'  # Replace with your actual access token

''' Step 2: Set up the request parameters'''

x_transaction_id = str(uuid.uuid4())
limit = 10  # Optional: Set the limit for the number of results returned
offset = 0  # Optional: Set the offset for pagination

place_id = '39000000CESL200' # Replace with the actual place ID 

''' Step 3: Make the API request to retrieve resources at place '''
def request_place_resources_from_api(access_token, place_id, x_transaction_id) -> dict:
    """Request place resources from the Enable GeoPlace API.
    Args:
        access_token (str): The access token for authentication.
        place_id (str): The ID of the place to query.
        x_transaction_id (str): A unique transaction ID for the request.
    Returns:
        dict: The JSON response containing place resources, or None if the request fails.
    """
    base_url = f"https://staging.apis.enable.net.nz/geoPlaceAPI/v1/place/{place_id}/resources"

    headers = {
        "content-type": "application/json",
        "Authorization": f"Bearer {access_token}",
        "X-Transaction-ID": x_transaction_id,
    }
    params = {
        "type": "ONT",
        "limit": limit,
        "offset": offset,
    }
    response = requests.get(base_url, headers=headers, params=params)

    if response.status_code == 200:
        print("Place resources retrieved successfully.")
        return response.json()
    else:
        print(f"Error retrieving place resources: {response.status_code} - {response.text}")
        return {"Error": f"{response.status_code} - {response.text}"}

if __name__ == "__main__":
    place_resources = request_place_resources_from_api(token, place_id, x_transaction_id)
    print(place_resources)

 

Place Export

Prerequisites

You must have access to a valid client ID and secret of an active application that has been granted the required geoPlaceAPI scopes in Enables Identity and Access Management platform, Okta. 

  • If you are not sure how to generate an access token, start here.
  • A valid version number for the file download

Example Python:

import requests
import uuid

'''
Step 1: Generate an access token via the Auth v2 API and ensure it has the following scopes
- geoPlaceAPI.exportPlaceData
- geoPlaceAPI.allowCorelogicData (Optional scope for CoreLogic data if Client has access to it.)
'''

token = 'your_access_token_here'  # Replace with your actual access token

''' Step 2: Set up the request parameters'''
x_transaction_id = str(uuid.uuid4())
version = '5'  # Specify the version of the file you want to download

''' Step 3: Make the API request to retrieve place csv file and store it locally'''
def request_csv_export_from_api(access_token, version, x_transaction_id):
    """Request a CSV export of place resources from the API."""
    base_url = "https://staging.apis.enable.net.nz/geoPlaceAPI/v1/place/export"

    # Define the API endpoint with the required version.
    url = f"{base_url}?version={version}"

    # Set up the authorisation header by replacing '{access_token}' with your access token. 
    headers = {
        "content-type": "application/json",
        'Authorization': f'Bearer {access_token}',
        "X-Transaction-ID": x_transaction_id
    }

    # Make the request to the Geographic Place API to get the presigned URL.
    response = requests.get(url, headers=headers)
    if response.status_code == 200:

        presigned_url = response.json().get('presignedUrl') 
        print("Presigned URL for CSV export successfully retrieved, downloading the file...")

        # Download the file from the presigned URL 
        response = requests.get(presigned_url)

        if response.status_code == 200:
            print("CSV export downloaded successfully, storing locally...")
            # Save the file locally 
            with open(f'place_csv_v{version}.csv', 'wb') as file: 
                file.write(response.content)
            print(f"CSV export saved as 'place_csv_v{version}.csv'")
        else:
            print(f"Error downloading CSV export: {response.status_code} - {response.text}")
    else:
        print(f"Error retrieving presigned URL: {response.status_code} - {response.text}")

if __name__ == "__main__":
    request_csv_export_from_api(token, version, x_transaction_id)