arcgis.ai module | ArcGIS API for Python

translate

class arcgis.ai.translate(text: str | list[str], to_language: list[str], from_language: str | None = 'en', *, gis: GIS | None = None)

Translates language strings passed to the desired array of output cultures.

Parameter	Description
text	Required string or list of strings. The text to translate.
to_language	Required list of strings. The list of languages to convert to. To see a list of supported languages, use the `languages` property of a `GIS` object. # Example argument formatting: result = translate( ... to_language = ["fr", "de"], # French, German ... )
from_language	Optional str. The source language. The default is US English. To see a list of supported languages, use the `languages` property of a `GIS` object.
gis	Optional `GIS`. The connection to the organization that has AI assistants enabled.

Returns:: An AIUtilsResponse object containing the translations accessible through the results property.

# Example usage
from arcgis.gis import GIS
from arcgis.ai import translate

# Connect to GIS (ensure you have the correct organization set up with AI assistants enabled)
gis = GIS(profile="your_profile")

# Translate a single string to French and German
response = translate(
    text="What departments border Moselle?",
    to_language=["fr", "de"],
    from_language="en",
)

print(response.results)
>>>[
    TranslateResult(
        translations=[
            {'text': 'Quels départements bordent la Moselle ?', 'to': 'fr'},
            {'text': 'Welche Départamentos grenzen an Moselle?', 'to': 'de'}
        ],
        key='key:1')
   ]

analyze_text

Analyzes the provided text against the given prompt(s) using AI capabilities. Allows users to submit text for analysis, which can include tasks such as sentiment analysis, entity recognition, and other natural language processing operations.

Parameter	Description
text	Required string. The text to analyze.
prompt	Required string, list of strings, or list of dictionaries. Defines the types analysis to perform. If a string or list of strings, these are the prompts or instructions. If a dictionary, keys are labels for each analysis type and values are the corresponding prompts/instructions. # Usage example 1 : argument as a string: result = analyze_text( ... prompt = "Summarize the following text.", ... ) # Usage example 2: argument as list of strings: result = analyze_text( ... prompt = [ "Summarize the following text.", "Extract key entities from the following text." ], ... ) # Usage example 3: argument as list of dictionaries: result = analyze_text( ... prompt = [ { "key": "summarize_prompt", "context": "Summarize the following text." }, { "key": "entities_prompt", "context": "Extract key entities from the following text." } ], ... )
to_language	Optional string. The output language for analysis. Default is “en”. To see a list of supported languages, use the `languages` property of a `GIS` object.
from_language	Optional string. The source language of the input text. Default is “en”. To see a list of supported languages, use the `languages` property of a `GIS` object.
gis	Optional `GIS`. The connection to the organization that has AI assistants enabled.

Returns:: AIUtilsResponse or AIUtilsException containing the the analysis results.

# Usage Example 1: Usage of the function:
from arcgis.gis import GIS
from arcgis.ai import analyze_text

# Connect to GIS (ensure you have the correct organization set up with AI assistants enabled)
gis = GIS(profile="your_organization_profile")

# Analyze text with a single prompt
response = analyze_text(
    text="ArcGIS is a powerful geographic information system.",
    prompt="What are the key entities in this text?",
    to_language="en",
    from_language="en",
)

print(response.success)
>>> True

print(response.results)
>>> [AnalyzeResult(success=True, value=['ArcGIS', 'geographic information system'], key='key:1')]


# Usage Example 2: Using multiple prompts:

response = analyze_text(
    text="ArcGIS is a powerful geographic information system.",
    prompt=[
        "What are the key entities in this text?",
        "Summarize the main idea of this text."
    ],
    to_language="en",
    from_language="en",
)
print(response)

# Usage Example 3: Using dictionary prompts:
response = analyze_text(
    text="ArcGIS is a powerful geographic information system.",
    prompt=[
        {
            "key": "entities",
            "context": "What are the key entities in this text?"
        },
        {
            "key": "summary",
            "context": "Summarize the main idea of this text."
        }
    ],
    to_language="en",
    from_language="en",
)

print(type(response))
>>> <class 'arcgis.ai._utils.AIUtilsResponse'>

print(response.results)
>>> [
     AnalyzeResult(success=True,
                   value=['ArcGIS', 'geographic information system'],
                   key='entities'),
     AnalyzeResult(success=True,
                   value='ArcGIS is described as a powerful geographic information system.',
                   key='summary')
    ]

analyze_image

Analyze the image using AI-powered models for object detection, text extraction, image description, and segmentation.

Note

The image must be hosted on an arcgis.com domain. Images from other domains will not be accepted. Currently supported formats: JPEG, PNG.

Parameter	Description
image	Required string. URL of the image (must be hosted on arcgis.com domain). Can also be a Base64 encoded string of the image data, but this is not recommended for large images.
prompt	Required string, list of strings, or list of dictionaries. This is the actual prompt or list of prompts describing the analysis to perform. # Example formats - Prompt as single string: result = analyze_image( ... prompt="List all the colors present in the image.", ... ) # Prompt as list of strings: result = analyze_image( ... prompt=[ "Describe the scene in the image.", "Identify any text in the image." ], ... ) # Prompt as list of dictionaries: result = analyze_image( ... prompt=[ { "key": "colors_prompt", "context": "List all the colors present in the image." }, { "key": "text_prompt", "context": "Identify any text in the image." } ], ... )
to_language	Optional str. The target language for translation. If not specified, the default is US English (“en”). To see a list of supported languages, use the `languages` property of a `GIS` object.
from_language	Optional str. The source language. The default is US English (“en”).
gis	Optional `GIS`. The connection to the organization that has AI assistants enabled.

Returns:: An AIUtilsResponse or AIUtilsException containing the analysis results.

# Usage Example 1: Using single prompt
from arcgis.gis import GIS
from arcgis.ai import analyze_image

gis = GIS(profile="your_profile")

image_url = "https://www.arcgis.com/sharing/rest/content/items/12345/info/iteminfo/thumbnail/thumbnail.png"
prompt = "Describe the scene in the image."

response = analyze_image(image=image_url, prompt=prompt, gis=gis)

if isinstance(response, AIUtilsResponse):
    print("Analysis successful!")
    print(response.value)
elif isinstance(response, AIUtilsException):
    print("Analysis failed!")
    print(response.value)

# Usage Example 2: Using list of strings for *prompt* argument
prompts = [
    "Describe the scene in the image.",
    "Identify any text in the image."
]

response = analyze_image(image=image_url, prompt=prompts, gis=gis)

if isinstance(response, AIUtilsResponse):
    print("Analysis successful!")
    print(response.value)
elif isinstance(response, AIUtilsException):
    print("Analysis failed!")
    print(response.value)

# Usage Example 3: Using list of dictionaries for *prompt* argument
dict_prompts = [
    {"key": "scene_description", "context": "Describe the scene in the image."},
    {"key": "text_identification", "context": "Identify any text in the image."}
]

response = analyze_image(image=image_url, prompt=dict_prompts, gis=gis)

if isinstance(response, AIUtilsResponse):
    print("Analysis successful!")
    print(response.value)
elif isinstance(response, AIUtilsException):
    print("Analysis failed!")
    print(response.value)

AIUtilsResponse

pydantic model arcgis.ai.AIUtilsResponse

Response model for AI utilities. This is common response structure for AI utility services like image analysis and text analysis.

field meta: AIUtilsResponseMetaData | dict | list | str | None = None: The metadata returned from the AI utility service.

field results: list[AnalyzeResult | TranslateResult | dict] | None = None: The results returned from the AI utility service. Results format varies based on service.

field success: bool [Required]: Indicates if the request was successful.

AIUtilsException

class arcgis.ai.AIUtilsException(error: dict)

Custom exception for AI utilities. This exception is raised when there is an error in the AI utility services like image analysis and text analysis.

add_note(object, /): Exception.add_note(note) – add a note to the exception

args

with_traceback(object, /): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

AIUtilsResponseMetaData

pydantic model arcgis.ai.AIUtilsResponseMetaData

Base metadata model for AI utilities. This is the common metadata structure for AI utility services like image analysis and text analysis.

field model: str | None = None: The model information returned from the AI utility service.

field usage: dict | None = None: The token usage information returned from the AI utility service.

AnalyzeResult

pydantic model arcgis.ai.AnalyzeResult

Model for the results returned from the analyze_image() function. Structure of the results object can vary based on the prompts used and the analysis performed. This is a flexible model that allows for any additional fields returned in the results.

field key: str | None = None: The key associated with the prompt if the prompt was provided as a dict with a key.

field success: bool [Required]: Indicates if the image analysis was successful.

field value: dict | list[str] | str | int | float | bool | None = None: The values returned from the image analysis.

TranslateResult

pydantic model arcgis.ai.TranslateResult

Model for the results returned from the translate() function. The structure of the results can vary based on the prompts used and the analysis performed. This is a flexible model that allows for any additional fields returned in the results.

field key: str | None = None: The key associated with the prompt if the prompt was provided as a dict with a key.

field translations: list[dict] | list | None = None: The values returned from the text analysis.