Get Conversions

This function allows you to retrieve multiple conversions by their unique identifiers in a single request. Conversions are kept for twelve months after the month they were made, then deleted, so older ones are no longer returned. Ids that are unknown, older or another project’s are left out of the answer instead of failing it, and the rows come back in no particular order, so match them by their uniqueId. See an example below:

You should authenticate/initialize Ip2Geo before using this method.

import { GetConversions } from '@ip2geo/sdk'

const conversionIds = ['uuid-1', 'uuid-2', 'uuid-3']

const { data, success, message } = await GetConversions({
    conversionIds: conversionIds
})

// Access the conversions
console.log(data.conversions) // Array of conversion objects

result = Ip2Geo.get_conversions(
    conversion_ids: ['uuid-1', 'uuid-2', 'uuid-3']
)

# Access the conversions
puts result['data']['conversions'] # Array of conversion objects

# {
#     'success' => true,
#     'code' => 200,
#     'message' => 'Success',
#     'data' => { 'conversions' => [...] },
#     '_req' => { 'reqId' => '...', 'resTime' => 123 }
# }

import ip2geo

result = ip2geo.get_conversions(
    conversion_ids=['uuid-1', 'uuid-2', 'uuid-3']
)

# Access the conversions
print(result['data']['conversions'])  # List of conversion objects

# {
#     'success': True,
#     'code': 200,
#     'message': 'Success',
#     'data': { 'conversions': [...] },
#     '_req': { 'reqId': '...', 'resTime': 123 }
# }

<?php

use Ip2Geo\Ip2Geo;

$result = Ip2Geo::getConversions(
    conversionIds: ['uuid-1', 'uuid-2', 'uuid-3'],
);

// Access the conversions
print_r($result['data']['conversions']); // Array of conversion arrays

// [
//     'success' => true,
//     'code' => 200,
//     'message' => 'Success',
//     'data' => ['conversions' => [...]],
//     '_req' => ['reqId' => '...', 'resTime' => 123],
// ]

With Select Fields

You can select specific fields from the conversion data object using the select parameter:

import { GetConversions, SELECT } from '@ip2geo/sdk'

const { data, success, message } = await GetConversions({
    conversionIds: ['uuid-1', 'uuid-2'],
    select: [
        SELECT.COUNTRY_NAME,
        SELECT.COUNTRY_CODE,
        SELECT.ASN_NAME
    ]
})

// Response data structure (each row keeps its uniqueId, so match rows by it):
// {
//     conversions: [
//         {
//             uniqueId: '01a12452-07a0-7a3b-8c41-d2e5f6a7b8c9',
//             data: {
//                 continent: {
//                     country: { name: 'United States', code: 'us' }
//                 },
//                 asn: { name: 'Cloudflare' }
//             }
//         },
//         ...
//     ]
// }

result = Ip2Geo.get_conversions(
    conversion_ids: ['uuid-1', 'uuid-2'],
    select: [
        Ip2Geo.select[:COUNTRY_NAME],
        Ip2Geo.select[:COUNTRY_CODE],
        Ip2Geo.select[:ASN_NAME]
    ]
)

# Response data structure (each row keeps its uniqueId, so match rows by it):
# {
#     'conversions' => [
#         {
#             'uniqueId' => '01a12452-07a0-7a3b-8c41-d2e5f6a7b8c9',
#             'data' => {
#                 'continent' => {
#                     'country' => { 'name' => 'United States', 'code' => 'us' }
#                 },
#                 'asn' => { 'name' => 'Cloudflare' }
#             }
#         },
#         ...
#     ]
# }

import ip2geo

result = ip2geo.get_conversions(
    conversion_ids=['uuid-1', 'uuid-2'],
    select=[
        ip2geo.SELECT['COUNTRY_NAME'],
        ip2geo.SELECT['COUNTRY_CODE'],
        ip2geo.SELECT['ASN_NAME'],
    ]
)

# Response data structure (each row keeps its uniqueId, so match rows by it):
# {
#     'conversions': [
#         {
#             'uniqueId': '01a12452-07a0-7a3b-8c41-d2e5f6a7b8c9',
#             'data': {
#                 'continent': {
#                     'country': { 'name': 'United States', 'code': 'us' }
#                 },
#                 'asn': { 'name': 'Cloudflare' }
#             }
#         },
#         ...
#     ]
# }

<?php

use Ip2Geo\Ip2Geo;

$result = Ip2Geo::getConversions(
    conversionIds: ['uuid-1', 'uuid-2'],
    select: [
        Ip2Geo::SELECT['COUNTRY_NAME'],
        Ip2Geo::SELECT['COUNTRY_CODE'],
        Ip2Geo::SELECT['ASN_NAME'],
    ],
);

// Response data structure (each row keeps its uniqueId, so match rows by it):
// [
//     'conversions' => [
//         [
//             'uniqueId' => '01a12452-07a0-7a3b-8c41-d2e5f6a7b8c9',
//             'data' => [
//                 'continent' => [
//                     'country' => ['name' => 'United States', 'code' => 'us'],
//                 ],
//                 'asn' => ['name' => 'Cloudflare'],
//             ],
//         ],
//         ...
//     ],
// ]

Parameters

conversionIdsArray<string>required

An array of unique identifiers (UUIDs) of the conversions to retrieve. Maximum 100 IDs per request.

selectArray<SelectField>

Select the fields to return. Geolocation fields, the SELECT Constants, are read under data, and the stored fields (id, uniqueId, status, startedAt, completedAt, createdAt) can be named as they are. uniqueId always comes along, so every row can be matched to its conversion. If not specified, every field is returned.

Response

successboolean

Whether the request was successful.

messagestring

Response message describing the result.

codenumber

HTTP status code.

dataobject | null

The response data containing:

conversions: Array of conversion objects (or partial objects if select was used)

_reqobject

Request metadata containing:

reqId: Unique request identifier.
resTime: Response time in milliseconds.

Parameters

conversion_idsArray<String>required

An array of unique identifiers (UUIDs) of the conversions to retrieve. Maximum 100 IDs per request.

selectArray<String>

Response

successBoolean

Whether the request was successful.

messageString

Response message describing the result.

codeInteger

HTTP status code.

dataHash | nil

The response data containing:

‘conversions’: Array of conversion hashes (or partial hashes if select was used)

_reqHash

Request metadata containing:

‘reqId’: Unique request identifier.
‘resTime’: Response time in milliseconds.

Parameters

conversion_idslist[str]required

A list of unique identifiers (UUIDs) of the conversions to retrieve. Maximum 100 IDs per request.

selectlist[str]

Response

successbool

Whether the request was successful.

messagestr

Response message describing the result.

codeint

HTTP status code.

datadict | None

The response data containing:

‘conversions’: List of conversion dicts (or partial dicts if select was used)

_reqdict

Request metadata containing:

‘reqId’: Unique request identifier.
‘resTime’: Response time in milliseconds.

Parameters

conversionIdsarrayrequired

An array of unique identifiers (UUIDs) of the conversions to retrieve. Maximum 100 IDs per request.

selectarray

Response

successbool

Whether the request was successful.

messagestring

Response message describing the result.

codeint

HTTP status code.

dataarray | null

The response data containing:

‘conversions’: Array of conversion arrays (or partial arrays if select was used)

_reqarray

Request metadata containing:

‘reqId’: Unique request identifier.
‘resTime’: Response time in milliseconds.

For all available SELECT constants and their values, see the SELECT Constants reference.

Error Handling

If any of the provided conversion IDs is not a UUIDv7 conversion id, the request fails and returns the list of invalid IDs:

const { data, success, message } = await GetConversions({
    conversionIds: ['valid-uuid', 'invalid-id', 'another-bad-id']
})

// Response:
// {
//     success: false,
//     message: 'One or more conversion IDs are invalid.',
//     data: { invalidIds: ['invalid-id', 'another-bad-id'] }
// }

result = Ip2Geo.get_conversions(
    conversion_ids: ['valid-uuid', 'invalid-id', 'another-bad-id']
)

# Response:
# {
#     'success' => false,
#     'message' => 'One or more conversion IDs are invalid.',
#     'data' => { 'invalidIds' => ['invalid-id', 'another-bad-id'] }
# }

result = ip2geo.get_conversions(
    conversion_ids=['valid-uuid', 'invalid-id', 'another-bad-id']
)

# Response:
# {
#     'success': False,
#     'message': 'One or more conversion IDs are invalid.',
#     'data': { 'invalidIds': ['invalid-id', 'another-bad-id'] }
# }

<?php

$result = Ip2Geo::getConversions(
    conversionIds: ['valid-uuid', 'invalid-id', 'another-bad-id'],
);

// Response:
// [
//     'success' => false,
//     'message' => 'One or more conversion IDs are invalid.',
//     'data' => ['invalidIds' => ['invalid-id', 'another-bad-id']],
// ]

Get Conversions

With Select Fields

Parameters

Response

Parameters

Response

Parameters

Response

Parameters

Response

Error Handling

Convert IPs into accurate location data in milliseconds.