Manage Data Resources

This tutorial shows how to manage data resources using the ZillionInfo API, including uploading files, importing data, and managing data resources.

Prerequisites

• A ZillionInfo account. If you don’t have one, you can sign up at ZillionInfo.
• An API key for authentication.
• Data files to upload (shapefiles, CSV files, etc.)

Steps

1. Upload a file

   First, you need to upload your data file to the platform. This step handles the initial file upload.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/upload/app/api/upload" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@/path/to/your/file.zip" \
     -F "codeType=UTF-8"

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/upload/app/api/upload"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY"
   }
   
   # Parameters
   params = {
       "codeType": "UTF-8"  # Optional encoding type
   }
   
   # Files to upload
   files = {
       "file": open("/path/to/your/file.zip", "rb")
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, params=params, files=files)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Store the response data for next steps
   upload_result = response.json()
   file_name = upload_result.get("fileName")
   record_id = upload_result.get("recordid")
   
   print(f"File uploaded: {file_name}, Record ID: {record_id}")

   Parameters:

   • file: The file to upload (e.g., a zipped shapefile or a CSV file)
   • codeType: (Optional) Encoding type, default is ‘UTF-8’

   Response:

   {
     "fileName": "my_data.zip",
     "recordid": 12345,
     "error": null
   }

   The response provides:

   • fileName: The name of the uploaded file
   • recordid: A record ID for the uploaded file, needed for the next steps
   • error: Error message if the upload failed

2. Import a shapefile

   After uploading a shapefile (zipped), you need to import it to create a data resource.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/upload/app/api/importShapefile" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "fileName": "my_data.zip",
       "recordid": 12345,
       "codeType": "UTF-8",
       "name": "My Shapefile Data"
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/upload/app/api/importShapefile"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "fileName": "my_data.zip",  # From previous step
       "recordid": 12345,          # From previous step
       "codeType": "UTF-8",
       "name": "My Shapefile Data"
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Store the data ID for future use
   shapefile_result = response.json()
   data_id = shapefile_result.get("id")
   
   print(f"Shapefile imported with ID: {data_id}")

   Parameters:

   • fileName: The name of the uploaded file from the previous step
   • recordid: The record ID from the previous step
   • codeType: Encoding type
   • name: The name for the new data resource

   Response:

   {
     "id": 6789,
     "geomType": "polygon",
     "dataName": "My Shapefile Data",
     "unitUrl": "workspace:layer",
     "bounds": "[-1, -1, 1, 1]",
     "error": null
   }

   The response provides:

   • id: The ID of the new data resource
   • geomType: The geometry type of the shapefile
   • dataName: The name of the data resource
   • unitUrl: The URL to access the data resource
   • bounds: The geographic bounds of the data
   • error: Error message if the import failed

3. Import a CSV file

   If you’ve uploaded a CSV file, you can import it to create a data resource.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/upload/app/api/importCsv" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "fileName": "my_data.csv",
       "recordid": 12346,
       "codeType": "UTF-8",
       "name": "My CSV Data"
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/upload/app/api/importCsv"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "fileName": "my_data.csv",  # From upload step
       "recordid": 12346,          # From upload step
       "codeType": "UTF-8",
       "name": "My CSV Data"
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Store the CSV data ID for future use
   csv_result = response.json()
   csv_id = csv_result.get("csv", {}).get("id")
   
   print(f"CSV imported with ID: {csv_id}")

   Parameters:

   • fileName: The name of the uploaded CSV file
   • recordid: The record ID from the upload step
   • codeType: Encoding type
   • name: The name for the new data resource

   Response:

   {
     "csv": {
       "id": 5678
     },
     "dataName": "My CSV Data",
     "error": null
   }

   The response provides:

   • csv.id: The ID of the new CSV data resource
   • dataName: The name of the data resource
   • error: Error message if the import failed

4. Get a list of data resources

   You can retrieve a list of all your data resources.

   cURL

   curl -X GET "https://services.zillioninfo.com/zi/data/app/api/getDataLists" \
     -H "Authorization: Bearer YOUR_API_KEY"

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/data/app/api/getDataLists"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY"
   }
   
   # Make the GET request
   response = requests.get(url, headers=headers)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Process the data list
   data_list = response.json().get("data", {})
   
   print("Available data resources:")
   for data_id, data_name in data_list.items():
       print(f"ID: {data_id}, Name: {data_name}")

   Response:

   {
     "data": {
       "6789": "My Shapefile Data",
       "5678": "My CSV Data"
     }
   }

   The response provides a dictionary mapping data IDs to data names.

5. Get data by name

   You can retrieve a data resource by its name.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/data/app/api/getDataByName" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My Shapefile Data",
       "type": "SHP"
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/data/app/api/getDataByName"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "name": "My Shapefile Data",
       "type": "SHP"  # Use "SHP" for spatial data or "CSV" for attribute data
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Get the data ID
   data_id = response.json().get("id")
   
   print(f"Data ID for '{payload['name']}': {data_id}")

   Parameters:

   • name: The name of the data resource
   • type: The type of data resource (“SHP” for spatial data or “CSV” for attribute data)

   Response:

   {
     "id": 6789,
     "error": null
   }

   The response provides:

   • id: The ID of the data resource
   • error: Error message if the request failed

6. Update a spatial data resource

   You can update the metadata of a spatial data resource.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/data/app/api/updateDataResource" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "id": 6789,
       "name": "Updated Shapefile Name",
       "description": "This is a detailed description of my shapefile data",
       "tags": "spatial,boundaries,analysis"
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/data/app/api/updateDataResource"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "id": 6789,
       "name": "Updated Shapefile Name",
       "description": "This is a detailed description of my shapefile data",
       "tags": "spatial,boundaries,analysis"
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Check for errors
   error = response.json().get("error")
   if error:
       print(f"Error updating data resource: {error}")
   else:
       print("Data resource updated successfully")

   Parameters:

   • id: The ID of the data resource to update
   • name: (Optional) The new name for the data resource
   • description: (Optional) A description of the data resource
   • tags: (Optional) Tags for the data resource, comma-separated

   Response:

   {
     "error": null
   }

   The response provides:

   • error: Error message if the update failed

7. Update an attribute data resource

   You can update the metadata of an attribute (CSV) data resource.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/data/app/api/updateCsvDataResource" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "id": 5678,
       "name": "Updated CSV Name",
       "description": "This is a detailed description of my CSV data",
       "tags": "attributes,statistics,analysis"
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/data/app/api/updateCsvDataResource"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "id": 5678,
       "name": "Updated CSV Name",
       "description": "This is a detailed description of my CSV data",
       "tags": "attributes,statistics,analysis"
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Check for errors
   error = response.json().get("error")
   if error:
       print(f"Error updating CSV data resource: {error}")
   else:
       print("CSV data resource updated successfully")

   Parameters:

   • id: The ID of the CSV data resource to update
   • name: (Optional) The new name for the data resource
   • description: (Optional) A description of the data resource
   • tags: (Optional) Tags for the data resource, comma-separated

   Response:

   {
     "error": null
   }

   The response provides:

   • error: Error message if the update failed

8. Delete a data resource

   You can delete a data resource when it’s no longer needed.

   cURL

   curl -X POST "https://services.zillioninfo.com/zi/data/app/api/deleteDataResource" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "dataId": 6789,
       "type": "SHP"
     }'

   Python

   import requests
   import json
   
   # API endpoint
   url = "https://services.zillioninfo.com/zi/data/app/api/deleteDataResource"
   
   # Headers
   headers = {
       "Authorization": "Bearer YOUR_API_KEY",
       "Content-Type": "application/json"
   }
   
   # Request payload
   payload = {
       "dataId": 6789,
       "type": "SHP"  # Use "SHP" for spatial data or "CSV" for attribute data
   }
   
   # Make the POST request
   response = requests.post(url, headers=headers, json=payload)
   
   # Print the response
   print(json.dumps(response.json(), indent=2))
   
   # Check for errors
   error = response.json().get("error")
   if error:
       print(f"Error deleting data resource: {error}")
   else:
       print("Data resource deleted successfully")

   Parameters:

   • dataId: The ID of the data resource to delete
   • type: The type of data resource (“SHP” for spatial data or “CSV” for attribute data)

   Response:

   {
     "error": null
   }

   The response provides:

   • error: Error message if the deletion failed

Best Practices

• Always check the error field in responses to ensure your requests were successful
• Use meaningful names and descriptions for your data resources
• Add relevant tags to make your data resources easier to find and categorize
• Delete unused data resources to free up space in your account

Next Steps

• Use your data resources with other ZillionInfo API services like VIS-STAMP
• Create workspaces to visualize and interact with your data
• Apply data processing tools to analyze and transform your data